Select the AWS region and architecture of your Lambda function. This documentation will update based on your selections.
-
-
-
region:
-
-
-
-
architecture:
-
-
-
-
-++++
-
-WARNING: The selected _AWS region_ and the _architecture_ must match the AWS region and architecture of your AWS Lambda function!
diff --git a/docs/monitoring-aws-lambda.asciidoc b/docs/monitoring-aws-lambda.asciidoc
deleted file mode 100644
index b792749e..00000000
--- a/docs/monitoring-aws-lambda.asciidoc
+++ /dev/null
@@ -1,254 +0,0 @@
-[[monitoring-aws-lambda]]
-= Monitoring AWS Lambda Functions
-
-Elastic APM lets you monitor your AWS Lambda functions.
-The natural integration of {apm-guide-ref}/apm-distributed-tracing.html[distributed tracing] into your AWS Lambda functions provides insights into the functions' execution and runtime behavior as well as their relationships and dependencies to other services.
-
-To get started with the setup of Elastic APM for your Lambda functions, checkout the language-specific guides:
-
-* {apm-node-ref}/lambda.html[Quick Start with APM on AWS Lambda - Node.js]
-* {apm-py-ref}/lambda-support.html[Quick Start with APM on AWS Lambda - Python]
-* {apm-java-ref}/aws-lambda.html[Quick Start with APM on AWS Lambda - Java]
-
-Note that AWS Step Functions are currently not supported by any of the languages.
-
-Learn more about the <> of Elastic APM for AWS Lambda.
-
-[[aws-lambda-arch]]
-== APM Architecture for AWS Lambda
-
-AWS Lambda uses a special execution model to provide a scalable, on-demand compute service for code execution. In particular, AWS freezes the execution environment of a lambda function when no active requests are being processed. This execution model poses additional requirements on APM in the context of AWS Lambda functions:
-
-1. To avoid data loss, APM data collected by APM agents needs to be flushed before the execution environment of a lambda function is frozen.
-2. Flushing APM data must be fast so as not to impact the response times of lambda function requests.
-
-To accomplish the above, Elastic APM agents instrument AWS Lambda functions and dispatch APM data via an https://docs.aws.amazon.com/lambda/latest/dg/using-extensions.html[AWS Lambda extension].
-
-Normally, during the execution of a Lambda function, there's only a single language process running in the AWS Lambda execution environment. With an AWS Lambda extension, Lambda users run a _second_ process alongside their main service/application process.
-
-image:images/architecture-white.png[image showing data flow from lambda function, to extension, to APM Server]
-
-By using an AWS Lambda extension, Elastic APM agents can send data to a local Lambda extension process, and that process will forward data on to APM Server asynchronously. The Lambda extension ensures that any potential latency between the Lambda function and the APM Server instance will not cause latency in the request flow of the Lambda function itself.
-
-[[aws-lambda-overhead]]
-== Performance impact and overhead
-As described in <>, 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.
-
-[float]
-=== Impact on the deployment package size
-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.
-
-[float]
-=== Performance impact
-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 <> 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.
-
-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.
-
-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:
-
-* {apm-node-ref}/performance-tuning.html[Performance Tuning - Node.js]
-* {apm-py-ref}/tuning-and-overhead.html[Performance Tuning - Python]
-* {apm-java-ref}/tuning-and-overhead.html[Performance Tuning - Java]
-
-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 {apm-java-ref}/aws-lambda.html#aws-lambda-caveats[Java Agent's AWS Lambda documentation].
-
-[[aws-lambda-config-options]]
-== Configuration options
-
-The recommended way of configuring the {apm-lambda-ext} and the APM agents on AWS Lambda is through the Lambda function's environment variables.
-
-The configuration options for the APM agents are documented in the corresponding language agents:
-
-* {apm-node-ref}/configuration.html[Configuration options - Node.js APM agent]
-* {apm-py-ref}/configuration.html[Configuration options - Python APM agent]
-* {apm-java-ref}/configuration.html[Configuration options - Java APM agent]
-
-NOTE: 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.
-
-NOTE: APM Central configuration is not supported when using the Elastic APM AWS Lambda extension
-
-[float]
-[[aws-lambda-config-relevant]]
-=== Relevant configuration options
-
-A list of relevant configuration options for the {apm-lambda-ext} is below.
-
-[float]
-[[aws-lambda-extension]]
-==== `ELASTIC_APM_LAMBDA_APM_SERVER`
-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.
-
-[float]
-==== `ELASTIC_APM_LAMBDA_AGENT_DATA_BUFFER_SIZE`
-The size of the buffer that stores APM agent data to be forwarded to the APM server. The _default_ is `100`.
-
-[float]
-[[aws-lambda-config-authentication-keys]]
-==== `ELASTIC_APM_SECRET_TOKEN` or `ELASTIC_APM_API_KEY`
-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 <> and use the <> 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 https://www.elastic.co/guide/en/apm/guide/current/configuration-anonymous.html[anonymous mode].
-
-[float]
-[[aws-lambda-config-secrets-manager-options]]
-==== `ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` or `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID`
-Instead of specifying the <> as plain text in your Lambda environment variables, you can <> 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.
-
-`ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` takes precedence over <>, and `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID` over <>, respectively.
-
-[float]
-==== `ELASTIC_APM_SERVICE_NAME`
-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.
-
-[float]
-[[aws-lambda-config-data-receiver-timeout]]
-==== `ELASTIC_APM_DATA_RECEIVER_TIMEOUT`
-
-[small]#Added in: v1.2.0. Replaces `ELASTIC_APM_DATA_RECEIVER_TIMEOUT_SECONDS`.#
-
-The {apm-lambda-ext}'s timeout value, for receiving data from the APM agent. The _default_ is `15s`.
-
-[float]
-==== `ELASTIC_APM_DATA_RECEIVER_SERVER_PORT`
-The port on which the {apm-lambda-ext} listens to receive data from the APM agent. The _default_ is `8200`.
-
-[float]
-[[aws-lambda-config-data-forwarder-timeout]]
-==== `ELASTIC_APM_DATA_FORWARDER_TIMEOUT`
-
-[small]#Added in: v1.2.0. Replaces `ELASTIC_APM_DATA_FORWARDER_TIMEOUT_SECONDS`.#
-
-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.
-
-[float]
-==== `ELASTIC_APM_SEND_STRATEGY`
-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`.
-
-* 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.
-* 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.
-
-[float]
-==== `ELASTIC_APM_LOG_LEVEL`
-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`.
-
-[float]
-==== `ELASTIC_APM_LAMBDA_CAPTURE_LOGS`
-
-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`.
-
-[float]
-==== `ELASTIC_APM_LAMBDA_VERIFY_SERVER_CERT`
-
-[small]#Added in: v1.3.0.#
-
-Whether to enable {apm-lambda-ext} to verify APM Server's certificate chain and host name.
-
-[float]
-==== `ELASTIC_APM_LAMBDA_SERVER_CA_CERT_PEM`
-
-[small]#Added in: v1.3.0.#
-
-The certificate passed as environment variable. To be used to verify APM Server's certificate chain if verify server certificate is enabled.
-
-[float]
-==== `ELASTIC_APM_SERVER_CA_CERT_FILE`
-
-[small]#Added in: v1.3.0.#
-
-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.
-
-[float]
-==== `ELASTIC_APM_SERVER_CA_CERT_ACM_ID`
-
-[small]#Added in: v1.3.0.#
-
-The ARN for Amazon-issued certificate. To be used to verify APM Server's certificate chain if verify server certificate is enabled.
-
-[NOTE]
-====
-You may see errors similar to the following in {stack} versions less than 8.5:
-
-[source,text]
-----
-client error: response status code: 400
-message: log: did not recognize object type
-----
-
-Users on older versions should disable log collection by setting `ELASTIC_APM_LAMBDA_CAPTURE_LOGS` to `false`.
-====
-
-[float]
-[[aws-lambda-config-deprecated]]
-=== Deprecated options
-
-[float]
-[[aws-lambda-config-data-receiver-timeout-seconds]]
-==== `ELASTIC_APM_DATA_RECEIVER_TIMEOUT_SECONDS`
-
-[small]#Deprecated in: v1.2.0. Use <> instead.#
-
-The {apm-lambda-ext}'s timeout value, in seconds, for receiving data from the APM agent. The _default_ is `15`.
-
-[float]
-[[aws-lambda-config-data-forwarder-timeout-seconds]]
-==== `ELASTIC_APM_DATA_FORWARDER_TIMEOUT_SECONDS`
-
-[small]#Deprecated in: v1.2.0. Use <> instead.#
-
-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.
-
-[[aws-lambda-secrets-manager]]
-== Using AWS Secrets Manager to manage APM authentication keys
-When using the config options <> for authentication of the {apm-lambda-ext}, the corresponding keys are specified in plain text in the environment variables of your Lambda function. If you prefer to securely store the authentication keys, you can use the AWS Secrets Manager and let the extension retrieve the actual keys from the AWS Secrets Manager. Follow the instructions below to set up the AWS Secrets Manager with the extension.
-
-[float]
-[[aws-lambda-secrets-manager-create-secret]]
-=== Step 1: Create a secret in the AWS Secrets Manager.
-https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html[Create a secret in the AWS Secrets Manager] for the {apm-guide-ref}/secret-token.html[APM Secret Token] or the {apm-guide-ref}/api-key.html[APM API key], depending on which one you prefer to use. Make sure to create the secret as a *Plaintext* typed secret and ensure it is created *in the same AWS region* as your target Lambda function that will use the secret.
-
-We recommend using the AWS-managed encryption key `aws/secretsmanager`. However, you can optionally create and select a custom KMS key for encryption. Note that with a custom encryption key, you will need additional key permissions on your Lambda function (see <>).
-
-include::./secrets-manager/create-secret-widget.asciidoc[]
-
-Remember your chosen secret name. You will use the secret name as the value for the config options <> when configuring your {apm-lambda-ext}.
-
-[float]
-[[aws-lambda-secrets-manager-permissions]]
-=== Step 2: Add permissions to your AWS Lambda function
-For your Lambda function to be able to retrieve the authentication key from the AWS Secrets Manager, you need to provide the following permissions to your Lambda function.
-
-include::./secrets-manager/add-permissions-widget.asciidoc[]
-
-[float]
-=== Step 3: Configure the {apm-lambda-ext}
-Finally, you will need to configure the {apm-lambda-ext} to use the secret from the Secrets Manager _instead of_ the value provided through <>.
-
-Provide the name of the secret you created in <> as the value for the <> config option, respectively, depending on whether you want to use the {apm-guide-ref}/secret-token.html[APM Secret Token] or the {apm-guide-ref}/api-key.html[APM API key].
-
-The language-specific instructions describe how to set environment variables for configuring AWS Lambda for Elastic APM:
-
-* {apm-node-ref}/lambda.html#_step_3_configure_apm_on_aws_lambda[Configure APM on AWS Lambda - Node.js]
-* {apm-py-ref}/lambda-support.html#_step_3_configure_apm_on_aws_lambda[Configure APM on AWS Lambda - Python]
-* {apm-java-ref}/aws-lambda.html#_step_3_configure_apm_on_aws_lambda[Configure APM on AWS Lambda - Java]
-
-That's it. With the first invocation (cold start) of your Lambda function you should see a log message from the {apm-lambda-ext} indicating that a secret from the secrets manager is used:
-
-[source, yml]
-----
-"Using the APM secret token retrieved from Secrets Manager."
-----
diff --git a/docs/reference/aws-lambda-config-options.md b/docs/reference/aws-lambda-config-options.md
new file mode 100644
index 00000000..b626a500
--- /dev/null
+++ b/docs/reference/aws-lambda-config-options.md
@@ -0,0 +1,152 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/apm/lambda/current/aws-lambda-config-options.html
+---
+
+# Configuration options [aws-lambda-config-options]
+
+The recommended way of configuring the {{apm-lambda-ext}} and the APM agents on AWS Lambda is through the Lambda function’s environment variables.
+
+The configuration options for the APM agents are documented in the corresponding language agents:
+
+* [Configuration options - Node.js APM agent](apm-agent-nodejs://reference/configuration.md)
+* [Configuration options - Python APM agent](apm-agent-php://reference/configuration.md)
+* [Configuration options - Java APM agent](apm-agent-java://reference/configuration.md)
+
+::::{note}
+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.
+::::
+
+
+::::{note}
+APM Central configuration is not supported when using the Elastic APM AWS Lambda extension
+::::
+
+
+
+## Relevant configuration options [aws-lambda-config-relevant]
+
+A list of relevant configuration options for the {{apm-lambda-ext}} is below.
+
+
+### `ELASTIC_APM_LAMBDA_APM_SERVER` [aws-lambda-extension]
+
+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.
+
+
+### `ELASTIC_APM_LAMBDA_AGENT_DATA_BUFFER_SIZE` [_elastic_apm_lambda_agent_data_buffer_size]
+
+The size of the buffer that stores APM agent data to be forwarded to the APM server. The *default* is `100`.
+
+
+### `ELASTIC_APM_SECRET_TOKEN` or `ELASTIC_APM_API_KEY` [aws-lambda-config-authentication-keys]
+
+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).
+
+
+### `ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` or `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID` [aws-lambda-config-secrets-manager-options]
+
+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.
+
+`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.
+
+
+### `ELASTIC_APM_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 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.
+
+
+### `ELASTIC_APM_DATA_RECEIVER_TIMEOUT` [aws-lambda-config-data-receiver-timeout]
+
+Added in: v1.2.0. Replaces `ELASTIC_APM_DATA_RECEIVER_TIMEOUT_SECONDS`.
+
+The {{apm-lambda-ext}}'s timeout value, for receiving data from the APM agent. The *default* is `15s`.
+
+
+### `ELASTIC_APM_DATA_RECEIVER_SERVER_PORT` [_elastic_apm_data_receiver_server_port]
+
+The port on which the {{apm-lambda-ext}} listens to receive data from the APM agent. The *default* is `8200`.
+
+
+### `ELASTIC_APM_DATA_FORWARDER_TIMEOUT` [aws-lambda-config-data-forwarder-timeout]
+
+Added in: v1.2.0. Replaces `ELASTIC_APM_DATA_FORWARDER_TIMEOUT_SECONDS`.
+
+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.
+
+
+### `ELASTIC_APM_SEND_STRATEGY` [_elastic_apm_send_strategy]
+
+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`.
+
+* 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.
+* 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.
+
+
+### `ELASTIC_APM_LOG_LEVEL` [_elastic_apm_log_level]
+
+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`.
+
+
+### `ELASTIC_APM_LAMBDA_CAPTURE_LOGS` [_elastic_apm_lambda_capture_logs]
+
+[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`.
+
+
+### `ELASTIC_APM_LAMBDA_VERIFY_SERVER_CERT` [_elastic_apm_lambda_verify_server_cert]
+
+Added in: v1.3.0.
+
+Whether to enable {{apm-lambda-ext}} to verify APM Server’s certificate chain and host name.
+
+
+### `ELASTIC_APM_LAMBDA_SERVER_CA_CERT_PEM` [_elastic_apm_lambda_server_ca_cert_pem]
+
+Added in: v1.3.0.
+
+The certificate passed as environment variable. To be used to verify APM Server’s certificate chain if verify server certificate is enabled.
+
+
+### `ELASTIC_APM_SERVER_CA_CERT_FILE` [_elastic_apm_server_ca_cert_file]
+
+Added in: v1.3.0.
+
+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.
+
+
+### `ELASTIC_APM_SERVER_CA_CERT_ACM_ID` [_elastic_apm_server_ca_cert_acm_id]
+
+Added in: v1.3.0.
+
+The ARN for Amazon-issued certificate. To be used to verify APM Server’s certificate chain if verify server certificate is enabled.
+
+::::{note}
+You may see errors similar to the following in {{stack}} versions less than 8.5:
+
+```text
+client error: response status code: 400
+message: log: did not recognize object type
+```
+
+Users on older versions should disable log collection by setting `ELASTIC_APM_LAMBDA_CAPTURE_LOGS` to `false`.
+
+::::
+
+
+
+## Deprecated options [aws-lambda-config-deprecated]
+
+
+### `ELASTIC_APM_DATA_RECEIVER_TIMEOUT_SECONDS` [aws-lambda-config-data-receiver-timeout-seconds]
+
+Deprecated in: v1.2.0. Use [`ELASTIC_APM_DATA_RECEIVER_TIMEOUT`](#aws-lambda-config-data-receiver-timeout) instead.
+
+The {{apm-lambda-ext}}'s timeout value, in seconds, for receiving data from the APM agent. The *default* is `15`.
+
+
+### `ELASTIC_APM_DATA_FORWARDER_TIMEOUT_SECONDS` [aws-lambda-config-data-forwarder-timeout-seconds]
+
+Deprecated in: v1.2.0. Use [`ELASTIC_APM_DATA_FORWARDER_TIMEOUT`](#aws-lambda-config-data-forwarder-timeout) instead.
+
+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.
+
diff --git a/docs/reference/aws-lambda-overhead.md b/docs/reference/aws-lambda-overhead.md
new file mode 100644
index 00000000..216f89f1
--- /dev/null
+++ b/docs/reference/aws-lambda-overhead.md
@@ -0,0 +1,29 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/apm/lambda/current/aws-lambda-overhead.html
+---
+
+# Performance impact and overhead [aws-lambda-overhead]
+
+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.
+
+
+## Impact on the deployment package size [_impact_on_the_deployment_package_size]
+
+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.
+
+
+## Performance impact [_performance_impact]
+
+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.
+
+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.
+
+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:
+
+* [Performance Tuning - Node.js](apm-agent-nodejs://reference/performance-tuning.md)
+* [Performance Tuning - Python](apm-agent-python://reference/performance-tuning.md)
+* [Performance Tuning - Java](apm-agent-java://reference/overhead-performance-tuning.md)
+
+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://reference/aws-lambda.md#aws-lambda-caveats).
+
diff --git a/docs/reference/aws-lambda-secrets-manager.md b/docs/reference/aws-lambda-secrets-manager.md
new file mode 100644
index 00000000..481ab6e4
--- /dev/null
+++ b/docs/reference/aws-lambda-secrets-manager.md
@@ -0,0 +1,278 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/apm/lambda/current/aws-lambda-secrets-manager.html
+---
+
+# Using AWS Secrets Manager to manage APM authentication keys [aws-lambda-secrets-manager]
+
+When using the config options [`ELASTIC_APM_SECRET_TOKEN` or `ELASTIC_APM_API_KEY`](/reference/aws-lambda-config-options.md#aws-lambda-config-authentication-keys) for authentication of the {{apm-lambda-ext}}, the corresponding keys are specified in plain text in the environment variables of your Lambda function. If you prefer to securely store the authentication keys, you can use the AWS Secrets Manager and let the extension retrieve the actual keys from the AWS Secrets Manager. Follow the instructions below to set up the AWS Secrets Manager with the extension.
+
+
+## Step 1: Create a secret in the AWS Secrets Manager. [aws-lambda-secrets-manager-create-secret]
+
+[Create a secret in the AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.md) for the [APM Secret Token](docs-content://solutions/observability/apps/secret-token.md) or the [APM API key](docs-content://solutions/observability/apps/api-keys.md), depending on which one you prefer to use. Make sure to create the secret as a **Plaintext** typed secret and ensure it is created **in the same AWS region** as your target Lambda function that will use the secret.
+
+We recommend using the AWS-managed encryption key `aws/secretsmanager`. However, you can optionally create and select a custom KMS key for encryption. Note that with a custom encryption key, you will need additional key permissions on your Lambda function (see [Step 2](#aws-lambda-secrets-manager-permissions)).
+
+:::::::{tab-set}
+
+::::::{tab-item} AWS Web Console
+In the Web Console of the AWS Secrets Manager, navigate to `Store a new secret`, select `Other type of secret` as the secret type, and choose the `Plaintext` tab for entering the secret value. Enter your APM secret token or APM API key value as a plain string (**not** as a JSON key value pair).
+
+
+
+Click `Next`, choose a secret name, and finalize the creation of the secret.
+::::::
+
+::::::{tab-item} AWS CLI
+Execute the following command to create a secret in the AWS Secrets Manager for your APM secret token or the APM API key:
+
+```bash
+aws secretsmanager create-secret \
+ --name MyAPMSecretToken \ <1>
+ --description "The Elastic APM secret token." \
+ --secret-string "YOUR_APM_AUTHENTICATION_KEY" <2>
+```
+
+1. Choose a secret name
+2. APM secret token or APM API key
+::::::
+
+::::::{tab-item} SAM
+The AWS Serverless Application Model (SAM) does not provide means to create a secret in the AWS Secrets Manager. Use one of the other options to create the secret.
+::::::
+
+::::::{tab-item} Serverless
+The Serverless Framework does not provide means to create a secret in the AWS Secrets Manager. Use one of the other options to create the secret.
+::::::
+
+::::::{tab-item} Terraform
+Add the following resources to your terraform file to create a secret in the AWS Secrets Manager for your APM secret token or the APM API key:
+
+```yaml
+...
+resource "aws_secretsmanager_secret" "apm_secret_token" {
+ name = "MyAPMSecretToken" <1>
+}
+
+resource "aws_secretsmanager_secret_version" "apm_secret_token_version" {
+ secret_id = aws_secretsmanager_secret.apm_secret_token.id
+ secret_string = "YOUR_APM_AUTHENTICATION_KEY" <2>
+}
+...
+```
+
+1. Choose a secret name
+2. APM secret token or APM API key
+::::::
+
+:::::::
+Remember your chosen secret name. You will use the secret name as the value for the config options [`ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` or `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID`](/reference/aws-lambda-config-options.md#aws-lambda-config-secrets-manager-options) when configuring your {{apm-lambda-ext}}.
+
+
+## Step 2: Add permissions to your AWS Lambda function [aws-lambda-secrets-manager-permissions]
+
+For your Lambda function to be able to retrieve the authentication key from the AWS Secrets Manager, you need to provide the following permissions to your Lambda function.
+
+:::::::{tab-set}
+
+::::::{tab-item} AWS Web Console
+* In the Web Console of your AWS Lambda function navigate to `Configuration` → `Permissions` and click on the link in the `Execution Role` section. This will lead you to the Web Console for the corresponding IAM role.
+* Select `Create inline policy` in the `Add permission` dropdown button and select the `JSON` tab to define the following JSON-based policy:
+
+ ```json
+ {
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": [
+ "secretsmanager:GetSecretValue"
+ ],
+ "Resource": [
+ "THE_ARN_OF_YOUR_SECRET"
+ ]
+ },
+ { <1>
+ "Effect": "Allow",
+ "Action": [
+ "kms:Decrypt"
+ ],
+ "Resource": [
+ "THE_ARN_OF_YOUR_CUSTOM_KMS_KEY"
+ ]
+ }
+ ]
+ }
+ ```
+
+ 1. This permission is ONLY needed if you use a custom KMS encryption key for your secret
+
+* Review and save the policy.
+::::::
+
+::::::{tab-item} AWS CLI
+* Create a policy file (`smElasticApmPolicy.json`) with the following content:
+
+ ```json
+ {
+ "Version": "2012-10-17",
+ "Statement": [
+ {
+ "Effect": "Allow",
+ "Action": [
+ "secretsmanager:GetSecretValue"
+ ],
+ "Resource": [
+ "THE_ARN_OF_YOUR_SECRET"
+ ]
+ },
+ { <1>
+ "Effect": "Allow",
+ "Action": [
+ "kms:Decrypt"
+ ],
+ "Resource": [
+ "THE_ARN_OF_YOUR_CUSTOM_KMS_KEY"
+ ]
+ }
+ ]
+ }
+ ```
+
+ 1. This permission is ONLY needed if you use a custom KMS encryption key for your secret
+
+* Retrieve the execution role name of your Lambda function with the following command:
+
+ ```bash
+ aws lambda get-function-configuration --function-name THE_NAME_OF_YOUR_FUNCTION | grep "Role"
+ ```
+
+* Attach the new policy to the execution role:
+
+ ```bash
+ aws iam put-role-policy \
+ --role-name NAME_OR_ARN_OF_THE_EXECUTION_ROLE \
+ --policy-name SecretsManagerAPMKeyPolicy \
+ --policy-document file://smElasticApmPolicy.json
+ ```
+::::::
+
+::::::{tab-item} SAM
+In your SAM `template.yml` file add the following policy to give the Lambda function access to the stored secret:
+
+```yaml
+...
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: 'AWS::Serverless-2016-10-31'
+Resources:
+ yourLambdaFunction:
+ Type: 'AWS::Serverless::Function'
+ Properties:
+ ...
+ Policies:
+ - Statement:
+ - Sid: SecretsManagerGetSecretValue
+ Effect: Allow
+ Action:
+ - secretsmanager:GetSecretValue
+ Resource: 'THE_ARN_OF_YOUR_SECRET'
+ - Sid: KMSDecrypt <1>
+ Effect: Allow
+ Action:
+ - kms:Decrypt
+ Resource: 'THE_ARN_OF_YOUR_CUSTOM_KMS_KEY'
+...
+```
+
+1. This permission is ONLY needed if you use a custom KMS encryption key for your secret
+::::::
+
+::::::{tab-item} Serverless
+In your serverless file add the following policy to give the Lambda function access to the stored secret:
+
+```yaml
+...
+provider:
+ iam:
+ role:
+ statements:
+ - Effect: Allow
+ Action: 'secretsmanager:GetSecretValue'
+ Resource: 'THE_ARN_OF_YOUR_SECRET'
+ - Effect: Allow <1>
+ Action: 'kms:Decrypt'
+ Resource: 'THE_ARN_OF_YOUR_CUSTOM_KMS_KEY'
+...
+```
+
+1. This permission is ONLY needed if you use a custom KMS encryption key for your secret
+::::::
+
+::::::{tab-item} Terraform
+Add the following policy and policy attachement resources to your terraform file to give the Lambda function access to the stored secret:
+
+```yaml
+...
+resource "aws_iam_role" "lambda_role" {
+ // Here is your Lambda execution role
+ ...
+}
+
+resource "aws_iam_policy" "secrets_manager_elastic_apm_policy" {
+ name = "secrets_manager_elastic_apm_policy"
+ description = "Allows the lambda function to access the APM authentication key stored in AWS Secrets Manager."
+
+ policy = <
+ "Action": [
+ "kms:Decrypt"
+ ],
+ "Effect": "Allow",
+ "Resource": "THE_ARN_OF_YOUR_CUSTOM_KMS_KEY"
+ }
+ ]
+}
+EOF
+}
+
+resource "aws_iam_policy_attachment" "secrets_manager_elastic_apm_policy_attach" {
+ role = aws_iam_role.lambda_role.name
+ policy_arn = aws_iam_policy.secrets_manager_elastic_apm_policy.arn
+}
+...
+```
+
+1. This permission is ONLY needed if you use a custom KMS encryption key for your secret
+::::::
+
+:::::::
+
+## Step 3: Configure the {{apm-lambda-ext}} [_step_3_configure_the_apm_lambda_ext]
+
+Finally, you will need to configure the {{apm-lambda-ext}} to use the secret from the Secrets Manager *instead of* the value provided through [`ELASTIC_APM_SECRET_TOKEN` or `ELASTIC_APM_API_KEY`](/reference/aws-lambda-config-options.md#aws-lambda-config-authentication-keys).
+
+Provide the name of the secret you created in [Step 1](#aws-lambda-secrets-manager-create-secret) as the value for the [`ELASTIC_APM_SECRETS_MANAGER_SECRET_TOKEN_ID` or `ELASTIC_APM_SECRETS_MANAGER_API_KEY_ID`](/reference/aws-lambda-config-options.md#aws-lambda-config-secrets-manager-options) config option, respectively, depending on whether you want to use the [APM Secret Token](docs-content://solutions/observability/apps/secret-token.md) or the [APM API key](docs-content://solutions/observability/apps/api-keys.md).
+
+The language-specific instructions describe how to set environment variables for configuring AWS Lambda for Elastic APM:
+
+* [Configure APM on AWS Lambda - Node.js](apm-agent-nodejs://reference/lambda.md#_step_3_configure_apm_on_aws_lambda)
+* [Configure APM on AWS Lambda - Python](apm-agent-python://reference/lambda-support.md#_step_3_configure_apm_on_aws_lambda)
+* [Configure APM on AWS Lambda - Java](apm-agent-java://reference/aws-lambda.md#_step_3_configure_apm_on_aws_lambda)
+
+That’s it. With the first invocation (cold start) of your Lambda function you should see a log message from the {{apm-lambda-ext}} indicating that a secret from the secrets manager is used:
+
+```yaml
+"Using the APM secret token retrieved from Secrets Manager."
+```
+
diff --git a/docs/reference/index.md b/docs/reference/index.md
new file mode 100644
index 00000000..0476d64b
--- /dev/null
+++ b/docs/reference/index.md
@@ -0,0 +1,21 @@
+---
+mapped_pages:
+ - https://www.elastic.co/guide/en/apm/lambda/current/aws-lambda-arch.html
+ - https://www.elastic.co/guide/en/apm/lambda/current/index.html
+---
+
+# APM Architecture for AWS Lambda [aws-lambda-arch]
+
+AWS Lambda uses a special execution model to provide a scalable, on-demand compute service for code execution. In particular, AWS freezes the execution environment of a lambda function when no active requests are being processed. This execution model poses additional requirements on APM in the context of AWS Lambda functions:
+
+1. To avoid data loss, APM data collected by APM agents needs to be flushed before the execution environment of a lambda function is frozen.
+2. Flushing APM data must be fast so as not to impact the response times of lambda function requests.
+
+To accomplish the above, Elastic APM agents instrument AWS Lambda functions and dispatch APM data via an [AWS Lambda extension](https://docs.aws.amazon.com/lambda/latest/dg/using-extensions.md).
+
+Normally, during the execution of a Lambda function, there’s only a single language process running in the AWS Lambda execution environment. With an AWS Lambda extension, Lambda users run a *second* process alongside their main service/application process.
+
+
+
+By using an AWS Lambda extension, Elastic APM agents can send data to a local Lambda extension process, and that process will forward data on to APM Server asynchronously. The Lambda extension ensures that any potential latency between the Lambda function and the APM Server instance will not cause latency in the request flow of the Lambda function itself.
+
diff --git a/docs/reference/toc.yml b/docs/reference/toc.yml
new file mode 100644
index 00000000..1dcfbe50
--- /dev/null
+++ b/docs/reference/toc.yml
@@ -0,0 +1,6 @@
+project: 'APM architecture for AWS Lambda reference'
+toc:
+ - file: index.md
+ - file: aws-lambda-overhead.md
+ - file: aws-lambda-config-options.md
+ - file: aws-lambda-secrets-manager.md
\ No newline at end of file
diff --git a/docs/release-notes.asciidoc b/docs/release-notes.asciidoc
deleted file mode 100644
index 49a370da..00000000
--- a/docs/release-notes.asciidoc
+++ /dev/null
@@ -1,6 +0,0 @@
-[[aws-lambda-release-notes]]
-== Release notes
-
-This section summarizes the changes in each release.
-
-include::../CHANGELOG.asciidoc[]
diff --git a/docs/release-notes/index.md b/docs/release-notes/index.md
new file mode 100644
index 00000000..0fe3bba4
--- /dev/null
+++ b/docs/release-notes/index.md
@@ -0,0 +1,110 @@
+---
+navigation_title: "Elastic APM AWS Lambda Extension"
+mapped_pages:
+ - https://www.elastic.co/guide/en/apm/lambda/current/aws-lambda-release-notes.html
+---
+
+# Elastic APM AWS Lambda Extension release notes [elastic-apm-aws-lambda-extension-release-notes]
+
+Review the changes, fixes, and more in each version of Elastic APM AWS Lambda Extension.
+
+To check for security updates, go to [Security announcements for the Elastic stack](https://discuss.elastic.co/c/announcements/security-announcements/31).
+
+% Release notes include only features, enhancements, and fixes. Add breaking changes, deprecations, and known issues to the applicable release notes sections.
+
+% ## version.next [elastic-apm-aws-lambda-extension-versionext-release-notes]
+% **Release date:** Month day, year
+
+% ### Features and enhancements [elastic-apm-aws-lambda-extension-versionext-features-enhancements]
+
+% ### Fixes [elastic-apm-aws-lambda-extension-versionext-fixes]
+
+## 1.5.1 [elastic-apm-aws-lambda-extension-151-release-notes]
+**Release date:** October 6, 2023
+
+### Fixes [elastic-apm-aws-lambda-extension-151-fixes]
+* Fix incorrect proxy transaction handling at shutdown due to not flushing the data before processing shutdown event. [412](https://github.com/elastic/apm-aws-lambda/pull/412).
+
+## 1.5.0 [elastic-apm-aws-lambda-extension-150-release-notes]
+**Release date:** September 13, 2023
+
+### Features and enhancements [elastic-apm-aws-lambda-extension-150-features-enhancements]
+* Use User-Agent header with Lambda extension version and propagate info from apm agents [404](https://github.com/elastic/apm-aws-lambda/pull/404)
+
+### Fixes [elastic-apm-aws-lambda-extension-150-fixes]
+* Log a warning, instead of failing a Lambda function, if auth retrieval from AWS Secrets Manager fails. Reporting APM data will not work, but the Lambda function invocations will proceed. [401](https://github.com/elastic/apm-aws-lambda/pull/401)
+
+## 1.4.0 [elastic-apm-aws-lambda-extension-140-release-notes]
+**Release date:** May 3, 2023
+
+### Features and enhancements [elastic-apm-aws-lambda-extension-150-features-enhancements]
+* [preview] Allow metadata in register transaction [384](https://github.com/elastic/apm-aws-lambda/pull/384)
+
+## 1.3.1 [elastic-apm-aws-lambda-extension-131-release-notes]
+**Release date:** April 4, 2023
+
+### Fixes [elastic-apm-aws-lambda-extension-131-fixes]
+* Print response body on error if decoding fails [382](https://github.com/elastic/apm-aws-lambda/pull/382)
+
+## 1.3.0 [elastic-apm-aws-lambda-extension-130-release-notes]
+**Release date:** April 22, 2023
+
+### Features and enhancements [elastic-apm-aws-lambda-extension-130-features-enhancements]
+* [preview] Create proxy transaction with error results if not reported by agent [315](https://github.com/elastic/apm-aws-lambda/pull/315)
+* Wait for the final platform report metrics on shutdown [347](https://github.com/elastic/apm-aws-lambda/pull/347)
+* Process platform report metrics when extension is lagging [358](https://github.com/elastic/apm-aws-lambda/pull/358)
+* Add TLS support [357](https://github.com/elastic/apm-aws-lambda/pull/357)
+
+## 1.2.0 [elastic-apm-aws-lambda-extension-120-release-notes]
+**Release date:** November 1, 2022
+
+### Features and enhancements [elastic-apm-aws-lambda-extension-120-features-enhancements]
+* Parse and log APM Server error responses, and backoff on critical errors [281](https://github.com/elastic/apm-aws-lambda/pull/281)
+* Disable CGO to prevent libc/ABI compatibility issues [292](https://github.com/elastic/apm-aws-lambda/pull/292)
+* Deprecate `ELASTIC_APM_DATA_RECEIVER_TIMEOUT_SECONDS` in favour of `ELASTIC_APM_DATA_RECEIVER_TIMEOUT` [294](https://github.com/elastic/apm-aws-lambda/pull/294)
+* Log shutdown reason on exit [297](https://github.com/elastic/apm-aws-lambda/pull/297)
+* Add support for collecting and shipping function logs to APM Server [303](https://github.com/elastic/apm-aws-lambda/pull/303)
+* Batch data collected from lambda logs API before sending to APM Server [314](https://github.com/elastic/apm-aws-lambda/pull/314)
+
+### Fixes [elastic-apm-aws-lambda-extension-120-fixes]
+* Fix possible data corruption while processing multiple log events [309](https://github.com/elastic/apm-aws-lambda/pull/309)
+
+## 1.1.0 [elastic-apm-aws-lambda-extension-110-release-notes]
+**Release date:** August 24, 2022
+
+### Features and enhancements [elastic-apm-aws-lambda-extension-110-features-enhancements]
+* Added support for Secret Manager [208](https://github.com/elastic/apm-aws-lambda/pull/208)
+* Added support for Lambda platform metrics [202](https://github.com/elastic/apm-aws-lambda/pull/202)
+* Migrated to AWS SDK for Go v2 [232](https://github.com/elastic/apm-aws-lambda/pull/232)
+* Make buffer size for agent data configurable [262](https://github.com/elastic/apm-aws-lambda/pull/262)
+* Add support for reproducible builds [237](https://github.com/elastic/apm-aws-lambda/pull/237)
+* Improve extension client error messages [259](https://github.com/elastic/apm-aws-lambda/pull/259)
+
+### Fixes [elastic-apm-aws-lambda-extension-110-fixes]
+* Log a warning when authentication with APM Server fails [228](https://github.com/elastic/apm-aws-lambda/pull/228)
+* Handle http.ErrServerClosed correctly [234](https://github.com/elastic/apm-aws-lambda/pull/234)
+* Handle main loop errors correctly [252](https://github.com/elastic/apm-aws-lambda/pull/252)
+* Avoid sending corrupted compressed data to APM Server [257](https://github.com/elastic/apm-aws-lambda/pull/257)
+* Avoid creating http transports on each info request [260](https://github.com/elastic/apm-aws-lambda/pull/260)
+* Randomise the initial grace period to avoid collisions [240](https://github.com/elastic/apm-aws-lambda/pull/240)
+* Handle metadata errors correctly [254](https://github.com/elastic/apm-aws-lambda/pull/254)
+* Always flush data to APM server before shutting down and avoid concurrent access to data channel [258](https://github.com/elastic/apm-aws-lambda/pull/258)
+
+## 1.0.2 [elastic-apm-aws-lambda-extension-102-release-notes]
+**Release date:** June 9, 2022
+
+### Fixes [elastic-apm-aws-lambda-extension-102-fixes]
+* Only add executables to extension [216](https://github.com/elastic/apm-aws-lambda/pull/216)
+
+## 1.0.1 [elastic-apm-aws-lambda-extension-101-release-notes]
+**Release date:** June 3, 2022
+
+### Features and enhancements [elastic-apm-aws-lambda-extension-101-features-enhancements]
+* Add support for building and pushing docker images [199](https://github.com/elastic/apm-aws-lambda/pull/199)
+
+## 1.0.0 [elastic-apm-aws-lambda-extension-100-release-notes]
+**Release date:** April 26, 2022
+
+### Features and enhancements [elastic-apm-aws-lambda-extension-100-features-enhancements]
+* First stable release of the Elastic APM AWS Lambda extension.
+
diff --git a/docs/release-notes/known-issues.md b/docs/release-notes/known-issues.md
new file mode 100644
index 00000000..2005c561
--- /dev/null
+++ b/docs/release-notes/known-issues.md
@@ -0,0 +1,20 @@
+---
+navigation_title: "Elastic APM AWS Lambda Extension"
+
+---
+
+# Elastic APM AWS Lambda Extension known issues [elastic-apm-aws-lambda-extension-known-issues]
+
+% Use the following template to add entries to this page.
+
+% :::{dropdown} Title of known issue
+% **Details**
+% On [Month/Day/Year], a known issue was discovered that [description of known issue].
+
+% **Workaround**
+% Workaround description.
+
+% **Resolved**
+% On [Month/Day/Year], this issue was resolved.
+
+:::
\ No newline at end of file
diff --git a/docs/release-notes/toc.yml b/docs/release-notes/toc.yml
new file mode 100644
index 00000000..3bbe7c82
--- /dev/null
+++ b/docs/release-notes/toc.yml
@@ -0,0 +1,3 @@
+toc:
+ - file: index.md
+ - file: known-issues.md
\ No newline at end of file
diff --git a/docs/secrets-manager/add-permissions-content.asciidoc b/docs/secrets-manager/add-permissions-content.asciidoc
deleted file mode 100644
index 5b4f7222..00000000
--- a/docs/secrets-manager/add-permissions-content.asciidoc
+++ /dev/null
@@ -1,191 +0,0 @@
-// tag::console[]
-- In the Web Console of your AWS Lambda function navigate to `Configuration` -> `Permissions` and click on the link in the `Execution Role` section.
-This will lead you to the Web Console for the corresponding IAM role.
-- Select `Create inline policy` in the `Add permission` dropdown button and select the `JSON` tab to define the following JSON-based policy:
-+
---
-[source,json]
-----
-{
- "Version": "2012-10-17",
- "Statement": [
- {
- "Effect": "Allow",
- "Action": [
- "secretsmanager:GetSecretValue"
- ],
- "Resource": [
- "THE_ARN_OF_YOUR_SECRET"
- ]
- },
- { <1>
- "Effect": "Allow",
- "Action": [
- "kms:Decrypt"
- ],
- "Resource": [
- "THE_ARN_OF_YOUR_CUSTOM_KMS_KEY"
- ]
- }
- ]
-}
-----
-<1> This permission is ONLY needed if you use a custom KMS encryption key for your secret
---
-- Review and save the policy.
-
-// end::console[]
-
-// tag::cli[]
-- Create a policy file (`smElasticApmPolicy.json`) with the following content:
-+
---
-[source,json]
-----
-{
- "Version": "2012-10-17",
- "Statement": [
- {
- "Effect": "Allow",
- "Action": [
- "secretsmanager:GetSecretValue"
- ],
- "Resource": [
- "THE_ARN_OF_YOUR_SECRET"
- ]
- },
- { <1>
- "Effect": "Allow",
- "Action": [
- "kms:Decrypt"
- ],
- "Resource": [
- "THE_ARN_OF_YOUR_CUSTOM_KMS_KEY"
- ]
- }
- ]
-}
-----
-<1> This permission is ONLY needed if you use a custom KMS encryption key for your secret
---
-- Retrieve the execution role name of your Lambda function with the following command:
-+
---
-[source,bash]
-----
-aws lambda get-function-configuration --function-name THE_NAME_OF_YOUR_FUNCTION | grep "Role"
-----
---
-- Attach the new policy to the execution role:
-+
---
-[source,bash]
-----
-aws iam put-role-policy \
- --role-name NAME_OR_ARN_OF_THE_EXECUTION_ROLE \
- --policy-name SecretsManagerAPMKeyPolicy \
- --policy-document file://smElasticApmPolicy.json
-----
---
-// end::cli[]
-
-// tag::sam[]
-
-In your SAM `template.yml` file add the following policy to give the Lambda function access to the stored secret:
-
-[source,yml]
-----
-...
-AWSTemplateFormatVersion: '2010-09-09'
-Transform: 'AWS::Serverless-2016-10-31'
-Resources:
- yourLambdaFunction:
- Type: 'AWS::Serverless::Function'
- Properties:
- ...
- Policies:
- - Statement:
- - Sid: SecretsManagerGetSecretValue
- Effect: Allow
- Action:
- - secretsmanager:GetSecretValue
- Resource: 'THE_ARN_OF_YOUR_SECRET'
- - Sid: KMSDecrypt <1>
- Effect: Allow
- Action:
- - kms:Decrypt
- Resource: 'THE_ARN_OF_YOUR_CUSTOM_KMS_KEY'
-...
-----
-<1> This permission is ONLY needed if you use a custom KMS encryption key for your secret
-
-// end::sam[]
-
-// tag::serverless[]
-In your serverless file add the following policy to give the Lambda function access to the stored secret:
-[source,yml]
-----
-...
-provider:
- iam:
- role:
- statements:
- - Effect: Allow
- Action: 'secretsmanager:GetSecretValue'
- Resource: 'THE_ARN_OF_YOUR_SECRET'
- - Effect: Allow <1>
- Action: 'kms:Decrypt'
- Resource: 'THE_ARN_OF_YOUR_CUSTOM_KMS_KEY'
-...
-----
-<1> This permission is ONLY needed if you use a custom KMS encryption key for your secret
-
-// end::serverless[]
-
-// tag::terraform[]
-Add the following policy and policy attachement resources to your terraform file to
-give the Lambda function access to the stored secret:
-[source,terraform]
-----
-...
-resource "aws_iam_role" "lambda_role" {
- // Here is your Lambda execution role
- ...
-}
-
-resource "aws_iam_policy" "secrets_manager_elastic_apm_policy" {
- name = "secrets_manager_elastic_apm_policy"
- description = "Allows the lambda function to access the APM authentication key stored in AWS Secrets Manager."
-
- policy = <
- "Action": [
- "kms:Decrypt"
- ],
- "Effect": "Allow",
- "Resource": "THE_ARN_OF_YOUR_CUSTOM_KMS_KEY"
- }
- ]
-}
-EOF
-}
-
-resource "aws_iam_policy_attachment" "secrets_manager_elastic_apm_policy_attach" {
- role = aws_iam_role.lambda_role.name
- policy_arn = aws_iam_policy.secrets_manager_elastic_apm_policy.arn
-}
-...
-----
-<1> This permission is ONLY needed if you use a custom KMS encryption key for your secret
-
-// end::terraform[]
diff --git a/docs/secrets-manager/add-permissions-widget.asciidoc b/docs/secrets-manager/add-permissions-widget.asciidoc
deleted file mode 100644
index 609d1485..00000000
--- a/docs/secrets-manager/add-permissions-widget.asciidoc
+++ /dev/null
@@ -1,99 +0,0 @@
-++++
-
-++++
\ No newline at end of file
diff --git a/docs/secrets-manager/create-secret-content.asciidoc b/docs/secrets-manager/create-secret-content.asciidoc
deleted file mode 100644
index d778fb37..00000000
--- a/docs/secrets-manager/create-secret-content.asciidoc
+++ /dev/null
@@ -1,58 +0,0 @@
-// tag::console[]
-
-In the Web Console of the AWS Secrets Manager, navigate to `Store a new secret`, select `Other type of secret` as the secret type, and choose the `Plaintext` tab for entering the secret value.
-Enter your APM secret token or APM API key value as a plain string (*not* as a JSON key value pair).
-
-image:images/secrets-manager.png[image showing the creation of a plaintext secret in Secrets Manager]
-
-Click `Next`, choose a secret name, and finalize the creation of the secret.
-
-// end::console[]
-
-// tag::cli[]
-Execute the following command to create a secret in the AWS Secrets Manager for your APM secret token or the APM API key:
-
-[source,bash]
-----
-aws secretsmanager create-secret \
- --name MyAPMSecretToken \ <1>
- --description "The Elastic APM secret token." \
- --secret-string "YOUR_APM_AUTHENTICATION_KEY" <2>
-----
-<1> Choose a secret name
-<2> APM secret token or APM API key
-
-// end::cli[]
-
-// tag::sam[]
-
-The AWS Serverless Application Model (SAM) does not provide means to create a secret in the AWS Secrets Manager. Use one of the other options to create the secret.
-
-// end::sam[]
-
-// tag::serverless[]
-
-The Serverless Framework does not provide means to create a secret in the AWS Secrets Manager. Use one of the other options to create the secret.
-
-// end::serverless[]
-
-// tag::terraform[]
-Add the following resources to your terraform file to create a secret in the AWS Secrets Manager for your APM secret token or the APM API key:
-
-[source,terraform]
-----
-...
-resource "aws_secretsmanager_secret" "apm_secret_token" {
- name = "MyAPMSecretToken" <1>
-}
-
-resource "aws_secretsmanager_secret_version" "apm_secret_token_version" {
- secret_id = aws_secretsmanager_secret.apm_secret_token.id
- secret_string = "YOUR_APM_AUTHENTICATION_KEY" <2>
-}
-...
-----
-<1> Choose a secret name
-<2> APM secret token or APM API key
-
-// end::terraform[]
diff --git a/docs/secrets-manager/create-secret-widget.asciidoc b/docs/secrets-manager/create-secret-widget.asciidoc
deleted file mode 100644
index 7ad716a1..00000000
--- a/docs/secrets-manager/create-secret-widget.asciidoc
+++ /dev/null
@@ -1,99 +0,0 @@
-++++
-