AWS lambda: Lambda managed instances system log format and event reference
Summary
Expands documentation for capacity provider system logs, adding structured JSON log entry format, event tables for FunctionLifecycle, Autoscaling, InstanceLifecycle, and ExecutionEnvironmentLifecycle events, and a metadata field reference including security-relevant fields such as KMS key ARNs, subnet IDs, security group IDs, and failure reason codes.
Security assessment
The change documents structured logging for Lambda capacity providers, including security-relevant metadata (KMS key ARNs, subnet IDs, security group IDs) and failure reason codes like KMSKeyAccessDenied and InsufficientRolePermissions. This improves auditability and troubleshooting of security-related failures but does not address a specific vulnerability or incident.
Evidence
+`kmsKeyArn` | String | The ARN of the AWS KMS key configured on the capacity provider.
Diff
diff --git a/lambda/latest/dg/lambda-managed-instances-monitoring-system-log-events.md b/lambda/latest/dg/lambda-managed-instances-monitoring-system-log-events.md index c60654b..2e8a4ee 100644 --- a//lambda/latest/dg/lambda-managed-instances-monitoring-system-log-events.md +++ b//lambda/latest/dg/lambda-managed-instances-monitoring-system-log-events.md @@ -7 +7 @@ -System log event level mapping +Log entry formatSystem log event level mappingFunctionLifecycle eventsAutoscaling eventsInstanceLifecycle eventsExecutionEnvironmentLifecycle eventsMetadata fields @@ -11 +11,45 @@ System log event level mapping -Lambda publishes system log events for capacity provider instance lifecycle operations. The following table shows the events that Lambda publishes and whether each event is logged based on your configured system log level. +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. + +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). + +## 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: + +Field | Type | Description +---|---|--- +`timestamp` | String | The time the log event was generated, in ISO 8601 format. +`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`. +`message` | String | A human-readable description of the event. +`metadata` | Object | Structured details about the event. The fields in this object vary by event. For a description of each field, see Metadata fields. + +The following example shows a system log entry for a function version that has become active: + + + { + "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" }` + + @@ -13 +56,0 @@ Lambda publishes system log events for capacity provider instance lifecycle oper -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). For details on the log entry format, see [Capacity provider system log format](./lambda-managed-instances-monitoring-log-format.html). @@ -17,9 +60,333 @@ For more information about configuring the system log level, see [Log-level filt -Event | Description | `DEBUG` | `INFO` | `WARN` ----|---|---|---|--- -Launching | Emitted when Lambda initiates an instance launch for the capacity provider. | Logged | Logged | Not logged -Launched | Emitted when an instance successfully transitions to an active state and is ready to serve invocations. | Logged | Logged | Not logged -LaunchFailed | Emitted when an instance launch attempt fails. | Logged | Logged | Logged -Terminating | Emitted when Lambda marks an instance for termination. | Logged | Logged | Not logged -Terminated | Emitted when an instance is successfully terminated. | Logged | Logged | Not logged -TerminateFailed | Emitted when Lambda fails to terminate an instance. | Logged | Logged | Logged -HealthCheckFailed | Emitted when an instance fails its health check and is marked as unhealthy. | Logged | Logged | Logged +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 +---|---|--- +`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. + +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. + +The following example shows a function version activation failure caused by an AWS KMS key issue: + + + { + "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` + + +`Scale-in blocked: function's minimum execution environments reached.` | `WARN` | Demand fell below the function version's minimum number of execution environments, so Lambda didn't scale in further. | + + * `action` (`scaleIn`) + * `minExecutionEnvironments` + * `executionEnvironmentCount` + + +`Scale-out blocked: capacity provider's maximum vCPU reached.` | `WARN` | Lambda attempted to scale out, but the capacity provider has reached its maximum vCPU limit. This event applies to the whole capacity provider and doesn't include function fields. |