AWS lambda: Restructure capacity provider system log event reference
Summary
Rewrites the capacity provider system log format page into a full event reference: renames sections, adds a log entry format with a JSON example and CloudWatch Logs filter patterns, a system log level mapping table, and new event tables for FunctionLifecycle, Autoscaling, InstanceLifecycle, and ExecutionEnvironmentLifecycle events, plus a consolidated metadata field list and execution environment failure reason codes (including KMS, IAM role, ECR image, security group, and subnet errors).
Security assessment
The change is a documentation restructure of the capacity provider system log format into an event reference. It is security-adjacent because the new tables and reason codes (KMSKeyAccessDenied, InsufficientRolePermissions, ImageAccessDenied, PermissionDenied, securityGroupIds, subnetIds, kmsKeyArn) help operators diagnose KMS/IAM/ECR/network misconfigurations via logs, but it documents no new security feature, best practice, or fixed vulnerability, so it is not security-issue related.
Evidence
+`KMSKeyAccessDenied` | Lambda was denied access to the AWS KMS key.
Diff
diff --git a/lambda/latest/dg/lambda-managed-instances-monitoring-log-format.md b/lambda/latest/dg/lambda-managed-instances-monitoring-log-format.md index 2ab738d..2e8a4ee 100644 --- a//lambda/latest/dg/lambda-managed-instances-monitoring-log-format.md +++ b//lambda/latest/dg/lambda-managed-instances-monitoring-log-format.md @@ -1 +1 @@ -[View a markdown version of this page](lambda-managed-instances-monitoring-log-format.md) +[View a markdown version of this page](lambda-managed-instances-monitoring-system-log-events.md) @@ -3 +3 @@ -[](/pdfs/lambda/latest/dg/lambda-dg.pdf#lambda-managed-instances-monitoring-log-format "Open PDF") +[](/pdfs/lambda/latest/dg/lambda-dg.pdf#lambda-managed-instances-monitoring-system-log-events "Open PDF") @@ -7 +7 @@ -JSON format for system logsMetadata fieldsExample log entry +Log entry formatSystem log event level mappingFunctionLifecycle eventsAutoscaling eventsInstanceLifecycle eventsExecutionEnvironmentLifecycle eventsMetadata fields @@ -9 +9 @@ JSON format for system logsMetadata fieldsExample log entry -# Capacity provider system log format +# Capacity provider system log event reference @@ -11 +11 @@ JSON format for system logsMetadata fieldsExample log entry -Capacity provider system logs use structured JSON format. JSON structured logs provide enhanced searchability and enable automated analysis of your capacity provider operational events. +Lambda publishes system log events for your capacity provider and for the function versions, Amazon EC2 instances, and execution environments that it manages. This topic describes the format of each log entry, the metadata fields that log entries can contain, and the events that Lambda publishes. @@ -13 +13 @@ Capacity provider system logs use structured JSON format. JSON structured logs p -## JSON format for system logs +For more information about configuring the system log level, see [Log-level filtering for capacity provider system logs](./lambda-managed-instances-monitoring-log-levels.html). @@ -15 +15,3 @@ Capacity provider system logs use structured JSON format. JSON structured logs p -Each system log entry is captured as a JSON object that contains key-value pairs with the following top-level fields: +## Log entry format + +Capacity provider system logs use structured JSON format. Each system log entry is a JSON object that contains the following top-level fields: @@ -20 +22,2 @@ Field | Type | Description -`level` | String | The log level of the event. +`level` | String | The log level of the event: `DEBUG`, `INFO`, `WARN`, or `ERROR`. +`operation` | String | The category of the event: `FunctionLifecycle`, `Autoscaling`, `InstanceLifecycle`, or `ExecutionEnvironmentLifecycle`. @@ -22 +25 @@ Field | Type | Description -`metadata` | Object | Structured metadata about the event. Contains fields that vary by event type. +`metadata` | Object | Structured details about the event. The fields in this object vary by event. For a description of each field, see Metadata fields. @@ -24 +27 @@ Field | Type | Description -## Metadata fields +The following example shows a system log entry for a function version that has become active: @@ -26 +28,0 @@ Field | Type | Description -The `metadata` object contains the following fields. Not all fields are present in every event. @@ -28 +30,99 @@ The `metadata` object contains the following fields. Not all fields are present -Field | Type | Description + { + "timestamp": "2026-07-22T18:09:30.000Z", + "level": "INFO", + "operation": "FunctionLifecycle", + "message": "Function version is active.", + "metadata": { + "capacityProviderArn": "arn:aws:lambda:us-west-2:111122223333:capacity-provider:my-capacity-provider", + "functionName": "my-function", + "functionVersionArn": "arn:aws:lambda:us-west-2:111122223333:function:my-function:1", + "functionVersion": "1", + "lastUpdateStatus": "Successful", + "executionEnvironmentCount": 3 + } + } + +Because each log entry is structured JSON, you can use CloudWatch Logs filter patterns to find related events. For example: + + * All events for a category: `{ $.operation = "FunctionLifecycle" }` + + * All events for a function: `{ $.metadata.functionName = "my-function" }` + + * All events for a function, plus capacity provider events that aren't tied to a specific function: `{ $.metadata.functionName = "my-function" || $.metadata.functionName NOT EXISTS }` + + * All warnings and errors: `{ $.level = "WARN" || $.level = "ERROR" }` + + + + +## System log event level mapping + +Each event has a fixed log level, shown in the event tables in this topic. The system log level that you configure for your capacity provider determines which events Lambda sends: + +Event level | System log level `DEBUG` | System log level `INFO` | System log level `WARN` +---|---|---|--- +`DEBUG` | Logged | Not logged | Not logged +`INFO` | Logged | Logged | Not logged +`WARN` | Logged | Logged | Logged +`ERROR` | Logged | Logged | Logged + +## FunctionLifecycle events + +`FunctionLifecycle` events track each function version that runs on the capacity provider, from activation through deletion. Messages are the same for numbered versions and `$LATEST.PUBLISHED`. To tell them apart, use the `functionVersion` field. + +All `FunctionLifecycle` events include the following metadata fields: `capacityProviderArn`, `functionName`, `functionVersionArn`, `functionVersion`, and `lastUpdateStatus`. + +Message | Level | When emitted | Additional metadata +---|---|---|--- +`Function version is being activated.` | `INFO` | A function version is added to the capacity provider and activation begins. | + + * `minExecutionEnvironments` + * `maxExecutionEnvironments` (only when configured) + + +`Function version is active.` | `INFO` | The function version is active and ready to serve invocations. | + + * `executionEnvironmentCount` + + +`Function version activation failed.` | `ERROR` | The function version failed to activate. | + + * `stateReasonCode` + +Depending on the reason code, also `kmsKeyArn`, `subnetIds`, or `securityGroupIds`. For details, see Capacity provider settings in failure events. +`Function scaling configuration is being updated.` | `INFO` | Lambda accepts an update to the function's scaling configuration and the update is in progress. | + + * `previousMinExecutionEnvironments` + * `previousMaxExecutionEnvironments` (only when configured) + * `newMinExecutionEnvironments` + * `newMaxExecutionEnvironments` (only when configured) + + +`Function scaling configuration updated.` | `INFO` | The scaling configuration update completed. | + + * `previousMinExecutionEnvironments` + * `previousMaxExecutionEnvironments` (only when configured) + * `newMinExecutionEnvironments` + * `newMaxExecutionEnvironments` (only when configured) + + +`Function scaling configuration update failed.` | `ERROR` | The scaling configuration update failed. | + + * `lastUpdateStatusReasonCode` + +Depending on the reason code, also `kmsKeyArn`, `subnetIds`, or `securityGroupIds`. For details, see Capacity provider settings in failure events. +`Function version is being deactivated.` | `INFO` | Lambda begins deactivating the function version. | None +`Function version is deactivated.` | `INFO` | The function version is fully deactivated. | None +`Function version is being deleted.` | `INFO` | Lambda begins removing the function version from the capacity provider. | None +`Function version is deleted.` | `INFO` | The function version is fully removed from the capacity provider. | None +`No available capacity: requesting new instance launch.` | `INFO` | The existing instances in the capacity provider can't host the execution environments that the function version needs, so Lambda requests new instances. | + + * `executionEnvironmentDeficit` + + + +### Capacity provider settings in failure events + +When the reason code of a `Function version activation failed.` or `Function scaling configuration update failed.` event points to a capacity provider setting, the event also includes that setting as configured on the capacity provider. This helps you identify which resource to fix. + +Reason codes | Field added | Value @@ -30,4 +130,3 @@ Field | Type | Description -`instanceId` | String | The Amazon EC2 instance ID associated with the event. -`availabilityZones` | Array of strings | The Availability Zone(s) associated with the event. -`instanceTypes` | Array of strings | The Amazon EC2 instance type(s) associated with the event. -`capacityProviderArn` | String | The ARN of the capacity provider. +`KMSKeyAccessDenied`, `KMSKeyNotFound`, `InvalidStateKMSKey`, `DisabledKMSKey` | `kmsKeyArn` | The AWS KMS key ARN configured on the capacity provider. +`InvalidSubnet`, `SubnetOutOfIPAddresses` | `subnetIds` | All subnet IDs configured on the capacity provider. +`InvalidSecurityGroup` | `securityGroupIds` | All security group IDs configured on the capacity provider. @@ -35 +134 @@ Field | Type | Description -## Example log entry +These fields contain the values configured on the capacity provider. For details about the failed launch, such as the instance type, Availability Zone, and Amazon EC2 error code, look for the corresponding `InstanceLifecycle` launch failure event. @@ -37 +136 @@ Field | Type | Description -The following example shows a system log entry for a successful instance launch: +The following example shows a function version activation failure caused by an AWS KMS key issue: @@ -41 +140,76 @@ The following example shows a system log entry for a successful instance launch: - "timestamp": "2025-07-01T14:31:15.456Z", + "timestamp": "2026-07-22T18:25:00.000Z", + "level": "ERROR", + "operation": "FunctionLifecycle", + "message": "Function version activation failed.", + "metadata": { + "capacityProviderArn": "arn:aws:lambda:us-west-2:111122223333:capacity-provider:my-capacity-provider", + "functionName": "my-function", + "functionVersionArn": "arn:aws:lambda:us-west-2:111122223333:function:my-function:1", + "functionVersion": "1", + "lastUpdateStatus": "Failed", + "stateReasonCode": "KMSKeyAccessDenied", + "kmsKeyArn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" + } + } + +## Autoscaling events + +`Autoscaling` events record scaling decisions that Lambda makes based on resource utilization, and the limits that prevent scaling. + +All `Autoscaling` events include the `capacityProviderArn` metadata field. Events that apply to a specific function version also include `functionName`, `functionVersionArn`, and `functionVersion`. Events that apply to the whole capacity provider don't include function fields. + +Message | Level | When emitted | Additional metadata +---|---|---|--- +`Scale-out triggered: Resource utilization exceeded threshold.` | `INFO` | The utilization of at least one resource exceeded its scale-out threshold. | + + * `action` (`scaleOut`) + * `resources` (the resources that exceeded their threshold) + * `currentCpuUtilization` (if `cpu` is in `resources`) + * `currentConcurrencyUtilization` (if `concurrency` is in `resources`) + + +`Scale-in triggered: Resource utilization fell below threshold.` | `INFO` | The utilization of all measured resources fell below their scale-in thresholds. | + + * `action` (`scaleIn`) + * `resources` (all measured resources) + * `currentCpuUtilization` (if `cpu` is in `resources`) + * `currentConcurrencyUtilization` (if `concurrency` is in `resources`) + + +`Scale-out blocked: function's maximum execution environments reached.` | `WARN` | Lambda attempted to scale out, but the function version already has its maximum number of execution environments. | + + * `action` (`scaleOut`) + * `maxExecutionEnvironments` + * `executionEnvironmentCount`