Lambda invokes your function in an execution environment, which provides a secure and isolated runtime environment. The execution environment manages the resources required to run your function. The execution environment also provides lifecycle support for the function's runtime and anyexternal extensions associated with your function.

The function's runtime communicates with Lambda using theRuntime API. Extensions communicate with Lambda using theExtensions API. Extensions can also receive log messages and other telemetry from the function by using theTelemetry API.

When you create your Lambda function, you specify configuration information, such as the amount of memory available and the maximum execution time allowed for your function. Lambda uses this information to set up the execution environment.

The function's runtime and each external extension are processes that run within the execution environment. Permissions, resources, credentials, and environment variables are shared between the function and the extensions.

Lambda execution environment lifecycle

Each phase starts with an event that Lambda sends to the runtime and to all registered extensions. The runtime and each extension indicate completion by sending aNext API request. Lambda freezes the execution environment when the runtime and each extension have completed and there are no pending events.

Init phase

In theInit phase, Lambda performs three tasks:

TheInit phase ends when the runtime and all extensions signal that they are ready by sending aNext API request. TheInit phase is limited to 10 seconds. If all three tasks do not complete within 10 seconds, Lambda retries theInit phase at the time of the first function invocation with the configured function timeout.

WhenLambda SnapStart is activated, theInit phase happens when you publish a function version. Lambda saves a snapshot of the memory and disk state of the initialized execution environment, persists the encrypted snapshot, and caches it for low-latency access. If you have a before-checkpointruntime hook, then the code runs at the end ofInit phase.

When you useprovisioned concurrency, Lambda initializes the execution environment when you configure the PC settings for a function. Lambda also ensures that initialized execution environments are always available in advance of invocations. You may see gaps between your function's invocation and initialization phases. Depending on your function's runtime and memory configuration, you may also see variable latency on the first invocation on an initialized execution environment.

For functions using on-demand concurrency, Lambda may occasionally initialize execution environments ahead of invocation requests. When this happens, you may also observe a time gap between your function's initialization and invocation phases. We recommend you to not take a dependency on this behavior.

Failures during the Init phase

If a function crashes or times out during theInit phase, Lambda emits error information in theINIT_REPORT log.

INIT_REPORT Init Duration: 1236.04 ms Phase: init Status: timeout

INIT_REPORT Init Duration: 1236.04 ms Phase: init Status: error Error Type: Extension.Crash

If theInit phase is successful, Lambda doesn't emit theINIT_REPORT log unlessSnapStart orprovisioned concurrency is enabled. SnapStart and provisioned concurrency functions always emitINIT_REPORT. For more information, seeMonitoring for Lambda SnapStart.

Restore phase (Lambda SnapStart only)

When you first invoke aSnapStart function and as the function scales up, Lambda resumes new execution environments from the persisted snapshot instead of initializing the function from scratch. If you have an after-restoreruntime hook, the code runs at the end of theRestore phase. You are charged for the duration of after-restore runtime hooks. The runtime must load and after-restore runtime hooks must complete within the timeout limit (10 seconds). Otherwise, you'll get a SnapStartTimeoutException. When theRestore phase completes, Lambda invokes the function handler (theInvoke phase).

Failures during the Restore phase

If theRestore phase fails, Lambda emits error information in theRESTORE_REPORT log.

RESTORE_REPORT Restore Duration: 1236.04 ms Status: timeout

RESTORE_REPORT Restore Duration: 1236.04 ms Status: error Error Type: Runtime.ExitError

For more information about theRESTORE_REPORT log, seeMonitoring for Lambda SnapStart.

Invoke phase

When a Lambda function is invoked in response to aNext API request, Lambda sends anInvoke event to the runtime and to each extension.

The function's timeout setting limits the duration of the entireInvoke phase. For example, if you set the function timeout as 360 seconds, the function and all extensions need to complete within 360 seconds. Note that there is no independent post-invoke phase. The duration is the sum of all invocation time (runtime + extensions) and is not calculated until the function and all extensions have finished executing.

The invoke phase ends after the runtime and all extensions signal that they are done by sending aNext API request.

Failures during the invoke phase

If the Lambda function crashes or times out during theInvoke phase, Lambda resets the execution environment. The following diagram illustrates Lambda execution environment behavior when there's an invoke failure:

In the previous diagram:

Shutdown phase

When Lambda is about to shut down the runtime, it sends aShutdown event to each registered external extension. Extensions can use this time for final cleanup tasks. TheShutdown event is a response to aNext API request.

Duration limit: The maximum duration of theShutdown phase depends on the configuration of registered extensions:

If the runtime or an extension does not respond to theShutdown event within the limit, Lambda ends the process using aSIGKILL signal.

After the function and all extensions have completed, Lambda maintains the execution environment for some time in anticipation of another function invocation. However, Lambda terminates execution environments every few hours to allow for runtime updates and maintenance—even for functions that are invoked continuously. You should not assume that the execution environment will persist indefinitely. For more information, seeImplement statelessness in functions.

When the function is invoked again, Lambda thaws the environment for reuse. Reusing the execution environment has the following implications:

Cold starts and latency

When Lambda receives a request to run a function via the Lambda API, the service first prepares an execution environment. During this initialization phase, the service downloads your code, starts the environment, and runs any initialization code outside of the main handler. Finally, Lambda runs the handler code.

In this diagram, the first two steps of downloading the code and setting up the environment are frequently referred to as a “cold start”. You are not charged for this time, but it does add latency to your overall invocation duration.

After the invocation completes, the execution environment is frozen. To improve resource management and performance, Lambda retains the execution environment for a period of time. During this time, if another request arrives for the same function, Lambda can reuse the environment. This second request typically finishes more quickly, since the execution environment is already fully set up. This is called a “warm start”.

Cold starts typically occur in under 1% of invocations. The duration of a cold start varies from under 100 ms to over 1 second. In general, cold starts are typically more common in development and test functions than production workloads. This is because development and test functions are usually invoked less frequently.

Reducing cold starts with Provisioned Concurrency

If you need predictable function start times for your workload,provisioned concurrency is the recommended solution to ensure the lowest possible latency. This feature pre-initializes execution environments, reducing cold starts.

For example, a function with a provisioned concurrency of 6 has 6 execution environments pre-warmed.

Optimizing static initialization

Static initialization happens before the handler code starts running in a function. This is the initialization code that you provide, that is outside of the main handler. This code is often used to import libraries and dependencies, set up configurations, and initialize connections to other services.

The following Python example shows importing, and configuring modules, and creating the Amazon S3 client during the initialization phase, before thelambda_handler function runs during invoke.

import osimport jsonimport cv2import loggingimport boto3s3 = boto3.client('s3')logger = logging.getLogger()logger.setLevel(logging.INFO)def lambda_handler(event, context):  # Handler logic...

The largest contributor of latency before function execution comes from initialization code. This code runs when a new execution environment is created for the first time. The initialization code is not run again if an invocation uses a warm execution environment. Factors that affect initialization code latency include:

There are a number of steps that developers can take to optimize static initialization latency. If a function has many objects and connections, you may be able to rearchitect a single function into multiple, specialized functions. These are individually smaller and each have less initialization code.

It’s important that functions only import the libraries and dependencies that they need. For example, if you only use Amazon DynamoDB in the AWS SDK, you can require an individual service instead of the entire SDK. Compare the following three examples:

// Instead of const AWS = require('aws-sdk'), use:const DynamoDB = require('aws-sdk/clients/dynamodb')// Instead of const AWSXRay = require('aws-xray-sdk'), use:const AWSXRay = require('aws-xray-sdk-core')// Instead of const AWS = AWSXRay.captureAWS(require('aws-sdk')), use:const dynamodb = new DynamoDB.DocumentClient()AWSXRay.captureAWSClient(dynamodb.service)

Static initialization is also often the best place to open database connections to allow a function to reuse connections over multiple invocations to the same execution environment. However, you may have large numbers of objects that are only used in certain execution paths in your function. In this case, you can lazily load variables in the global scope to reduce the static initialization duration.

Avoid global variables for context-specific information. If your function has a global variable that is used only for the lifetime of a single invocation and is reset for the next invocation, use a variable scope that is local to the handler. Not only does this prevent global variable leaks across invocations, it also improves the static initialization performance.

Thanks for letting us know we're doing a good job!

If you've got a moment, please tell us what we did right so we can do more of it.

Thanks for letting us know this page needs work. We're sorry we let you down.

If you've got a moment, please tell us how we can make the documentation better.