Monitoring customer-managed runtimes
As a runtime publisher, you don't have access to the Lambda Event Functions that use your runtime, because the functions run in your consumers' accounts. To help you monitor your runtime, Lambda publishes runtime metrics to Amazon CloudWatch in your account. AWS CloudTrail also delivers events to your account when other accounts configure functions to use your runtime, or try to. Use the metrics to check the health of each runtime version and runtime alias. You can also track the progress of a runtime update and see how much each runtime resource is used.
This topic describes the runtime metrics and how to use them. It then shows you how to view the metrics, create an alarm on the error rate of a runtime alias, and compare two runtime versions. It also describes the CloudTrail events that Lambda logs for customer-managed runtimes.
Runtime metrics
Lambda publishes the following metrics for each customer-managed runtime. The metrics count invocations of all functions that use the runtime.
| Metric | Description | Useful statistic |
|---|---|---|
RuntimeInvocations |
The number of invocations of functions that use the runtime. This count includes successful invocations and invocations that result in an error. | Sum |
RuntimeInvocationErrors |
The number of invocations of functions that use the runtime that result in a function error. | Sum |
Lambda publishes runtime metrics in the AWS/Lambda namespace.
To calculate an error rate, divide RuntimeInvocationErrors by RuntimeInvocations with CloudWatch metric math. For more information, see Using math expressions with CloudWatch metrics in the Amazon CloudWatch User Guide.
Dimensions
You can view each runtime metric by the following dimensions.
| Dimension | Description |
|---|---|
Runtime |
The name of the runtime, for example, companyphp8. Use the runtime name, not the runtime ARN. When you use this dimension alone, the data includes all versions and aliases of the runtime. |
RuntimeVersion |
The name of the runtime version, for example, v8.3.2. Data for this dimension includes invocations that use this version, no matter which alias resolved to it. |
RuntimeAlias |
The name of the runtime alias, for example, prod. Data for this dimension includes invocations of functions that use this alias. Invocations of functions that are pinned to a runtime version aren't included. |
Lambda publishes each runtime metric with the following dimension combinations:
-
Runtime -
RuntimeandRuntimeAlias -
RuntimeandRuntimeVersion -
Runtime,RuntimeAlias, andRuntimeVersion
Lambda doesn't publish the RuntimeAlias or RuntimeVersion dimension alone. Every query must include the Runtime dimension.
Lambda doesn't count invocations of functions that are pinned to a runtime version in Manual mode in the RuntimeAlias dimension. These invocations appear only when you view a metric by Runtime alone, or by Runtime and RuntimeVersion.
Granularity
Lambda publishes runtime metrics at 1-minute granularity, the same as function metrics. You can use the metrics to act during a rollout, for example, to stop an alias update when the error rate rises.
Scope and privacy
Runtime metrics appear in the runtime publisher's account, which is the account that owns the runtime. Lambda publishes the metrics in each AWS Region separately. For a runtime that you deploy to several Regions, check the metrics in each Region. For more information, see Deploying runtimes in multiple Regions.
In each Region, the metrics include invocations of all functions that use the runtime, across all accounts and organizations. The metrics don't reveal function names, account IDs, or other data about runtime consumers. You can see the impact of a runtime change across your whole consumer base, without access to your consumers' functions.
When a function uses a customer-managed runtime, Lambda includes its invocations in the aggregate metrics in the publisher's account. Runtime consumers continue to see the standard metrics for their own functions. Customer-managed runtimes don't change function metrics.
Cost
Lambda doesn't charge extra for runtime metrics. Standard CloudWatch charges apply when you use the metrics, for example, for alarms, dashboards, and API requests. For more information, see Amazon CloudWatch pricing
How to use runtime metrics
You can use runtime metrics for the following tasks.
Check rollout health
When you update a runtime alias to a new runtime version, compare the error rates of the new and previous versions. If the new version has a higher error rate under similar traffic, the update might have caused a problem.
You can also compare the error rates of your aliases. For example, check whether errors are concentrated in the prod alias after you update it. We recommend that you create a CloudWatch alarm on the error rate of each alias. Stop your rollout or roll back when an alarm goes into the ALARM state. For more information about rollouts and rollbacks, see Deploying runtime updates.
Track rollout progress
Functions pick up an alias update at their next cold start, so a runtime update reaches functions gradually. To see how far a rollout has progressed, view the RuntimeInvocations metric by runtime version. As Lambda replaces execution environments, invocations shift from the previous version to the new version.
Check usage before you delete or deprecate
Lambda doesn't check whether functions use a runtime resource before you delete it. Before you delete a runtime version or alias, or deprecate a runtime, check its RuntimeInvocations metric. The metric shows which resources functions still use, and how many invocations a change might affect.
Choose a time range that's long enough to include functions that run infrequently, for example, 14–30 days.
If the RuntimeInvocations metric is zero, no functions invoked the resource during that time range. A zero value doesn't prove that no functions are configured to use the resource. An idle function might be invoked later. In addition, the metric for an alias doesn't include functions that are pinned to a runtime version. Their invocations appear only under the runtime version. Also check with your runtime consumers.
For more information, see Deleting and restoring runtimes and Runtime lifecycle.
View runtime metrics
You can view runtime metrics with the CloudWatch console or the AWS Command Line Interface (AWS CLI).
Create an error rate alarm for a runtime alias
To detect problems during a rollout, create a CloudWatch alarm on the error rate of each runtime alias. The following example creates an alarm for the prod alias. The alarm goes into the ALARM state when the error rate is greater than 1% for 3 of 5 minutes. It then sends a notification to an Amazon Simple Notification Service (Amazon SNS) topic. Your deployment pipeline can stop or roll back the rollout when the alarm goes into the ALARM state.
Compare two runtime versions
During a rollout, compare the new runtime version with the previous version. The following examples compare runtime versions v8.3.1 and v8.3.2. They show the error rate and the number of invocations for each version.
Logging customer-managed runtime API calls with CloudTrail
AWS CloudTrail logs API calls for runtimes, runtime versions, runtime aliases, resource-based policies, and tags as management events. The event source is lambda.amazonaws.com. You can use these events to see who changed a runtime resource, and when. For more information about how Lambda works with CloudTrail, including Event history and trails, see Logging AWS Lambda API calls using AWS CloudTrail.
The following table lists the CloudTrail event names for customer-managed runtime API calls.
| Resource | Event names |
|---|---|
| Runtime | CreateRuntime, GetRuntime, ListRuntimes, UpdateRuntime, DeleteRuntime, RestoreRuntime |
| Runtime version | CreateRuntimeVersion, GetRuntimeVersion, ListRuntimeVersions, UpdateRuntimeVersion, DeleteRuntimeVersion |
| Runtime alias | CreateRuntimeAlias, GetRuntimeAlias, ListRuntimeAliases, UpdateRuntimeAlias, DeleteRuntimeAlias |
| Resource-based policy | PutResourcePolicy, GetResourcePolicy, DeleteResourcePolicy |
| Tags | TagResource20170331v2, UntagResource20170331v2, ListTags20170331 |
Function invocations are data events for the AWS::Lambda::Function resource type, the same as for other functions. CloudTrail doesn't have data events specific to customer-managed runtimes. For more information, see Lambda data events in CloudTrail.
Events when a function uses a runtime
The lambda:AssociateRuntimeAlias and lambda:AssociateRuntimeVersion actions are permission checks only. CloudTrail doesn't log them as separate events. Instead, CloudTrail logs the function operation that uses the runtime:
-
CreateFunction20150331– When you create a function that uses a runtime alias. -
UpdateFunctionConfiguration20150331v2– When you set or change the runtime alias of a function. -
PutRuntimeManagementConfig– When you pin a function to a runtime version in Manual mode.
These events include the runtime configuration of the function:
-
In
CreateFunctionandUpdateFunctionConfigurationevents,requestParametersandresponseElementsinclude aruntimeConfigobject with theruntimeArnandruntimeAlias. TheresponseElementsalso includeruntimeVersionConfig, which shows the runtime version that the alias pointed to. -
In
PutRuntimeManagementConfigevents,requestParametersandresponseElementsinclude theruntimeVersionArn. -
The
resourceslist includes the function and the runtime resource. The function has the typeAWS::Lambda::Function, orAWS::Lambda::Versionfor a published version. The runtime resource has the typeAWS::Lambda::RuntimeAliasorAWS::Lambda::RuntimeVersion.
When the function and the runtime are in different accounts, CloudTrail delivers these events to both accounts, whether Lambda allows or denies the request. As a runtime publisher, you can review these events in your own account to see which accounts use your runtime. For allowed requests, your copy also includes the function ARN in requestParameters and resources.
CloudTrail logs some function operations only in the consumer's account. These include operations that don't reference your runtime, such as an UpdateFunctionConfiguration request that changes only the timeout. They also include PutRuntimeManagementConfig requests that set Auto or Function update mode. Requests for a runtime that doesn't exist are also logged only in the consumer's account.
In the runtime publisher's copy, the userIdentity field identifies the caller only by account. The type is AWSAccount, and the accountId is the consumer's account ID. The publisher's copy doesn't include the IAM principal that made the request. Both copies have the same requestID and sharedEventID.
If Lambda denies the request, CloudTrail logs the event under the function operation event name with the errorCode AccessDenied. For example, this happens when the runtime's resource-based policy doesn't allow lambda:AssociateRuntimeAlias. The errorMessage names the action that was denied. The runtime publisher's copy of a denied event doesn't include requestParameters.
When you change the runtime alias of a function, the UpdateFunctionConfiguration event records the new alias. To find the alias that the function used before, review earlier events for the function.
The following example shows a CreateFunction event for a function that uses the prod alias of the companyphp8 runtime. The example omits some fields.
{ "eventVersion": "1.11", "userIdentity": { "type": "IAMUser", "principalId": "AIDAEXAMPLE", "arn": "arn:aws:iam::123456789012:user/my-user", "accountId": "123456789012", "userName": "my-user" }, "eventTime": "2026-11-06T18:09:29Z", "eventSource": "lambda.amazonaws.com", "eventName": "CreateFunction20150331", "awsRegion": "us-east-1", "sourceIPAddress": "192.0.2.0", "requestParameters": { "functionName": "my-function", "runtime": "custom", "role": "arn:aws:iam::123456789012:role/my-lambda-role", "handler": "index.handler", "architectures": [ "x86_64" ], "runtimeConfig": { "runtimeArn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8", "runtimeAlias": "prod" } }, "responseElements": { "functionName": "my-function", "functionArn": "arn:aws:lambda:us-east-1:123456789012:function:my-function", "runtime": "custom", "version": "$LATEST", "runtimeConfig": { "runtimeArn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8", "runtimeAlias": "prod" }, "runtimeVersionConfig": { "runtimeVersionArn": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8/version/v8.3.2" } }, "requestID": "EXAMPLE-1111-2222-3333-444444444444", "eventID": "EXAMPLE-5555-6666-7777-888888888888", "readOnly": false, "resources": [ { "accountId": "123456789012", "type": "AWS::Lambda::RuntimeAlias", "ARN": "arn:aws:lambda:us-east-1:123456789012:runtime/companyphp8/alias/prod" }, { "accountId": "123456789012", "type": "AWS::Lambda::Function", "ARN": "arn:aws:lambda:us-east-1:123456789012:function:my-function" } ], "eventType": "AwsApiCall", "managementEvent": true, "recipientAccountId": "123456789012", "eventCategory": "Management" }
Track runtime alias changes
When you point a runtime alias to a different runtime version, CloudTrail logs an UpdateRuntimeAlias event in your account. The requestParameters include the name of the new runtime version in runtimeVersion. The responseElements include the ARN of the new version in runtimeVersionArn.
Functions that use the alias pick up the new version at their next cold start. CloudTrail doesn't log a separate event for each function. To see which version an alias pointed to at a given time, review the CreateRuntimeAlias and UpdateRuntimeAlias events for the alias. To see how invocations shift to the new version across all functions, use the runtime metrics. For more information, see Track rollout progress. To confirm which runtime version a specific function uses, check the INIT_START line in the function's logs. Lambda writes this line each time it creates an execution environment, and the line includes the runtime version and runtime version ARN. Function owners can see these logs in their own accounts. For more information, see Check which runtime version your function uses.
Related topics
For more information about tasks that use runtime metrics and CloudTrail events, see the following topics: