Logging AWS Lambda API calls with AWS CloudTrail - AWS Lambda

Logging AWS Lambda API calls with AWS CloudTrail

AWS Lambda is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in AWS Lambda. CloudTrail captures API calls for AWS Lambda as events. The calls captured include calls from the AWS Lambda console and code calls to the AWS Lambda API operations. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for AWS Lambda. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in Event history. Using the information collected by CloudTrail, you can determine the request that was made to AWS Lambda, the IP address from which the request was made, who made the request, when it was made, and additional details.

To learn more about CloudTrail, including how to configure and enable it, see the AWS CloudTrail User Guide.

AWS Lambda information in CloudTrail

CloudTrail is enabled on your AWS account when you create the account. When supported event activity occurs in AWS Lambda, that activity is recorded in a CloudTrail event along with other AWS service events in Event history. You can view, search, and download recent events in your AWS account. For more information, see Viewing events with CloudTrail event history.

For an ongoing record of events in your AWS account, including events for AWS Lambda, you create a trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see the following:

AWS Lambda supports logging the following actions as events in CloudTrail log files:

Every log entry contains information about who generated the request. The user identity information in the log helps you determine whether the request was made with root or IAM user credentials, with temporary security credentials for a role or federated user, or by another AWS service. For more information, see the userIdentity field in the CloudTrail event reference.

You can store your log files in your bucket for as long as you want, but you can also define Amazon S3 lifecycle rules to archive or delete log files automatically. By default, your log files are encrypted by using Amazon S3 server-side encryption (SSE).

You can choose to have CloudTrail publish Amazon SNS notifications when new log files are delivered if you want to take quick action upon log file delivery. For more information, see Configuring Amazon SNS notifications for CloudTrail.

You can also aggregate AWS Lambda log files from multiple AWS regions and multiple AWS accounts into a single S3 bucket. For more information, see Working with CloudTrail log files.

Understanding AWS Lambda log file entries

CloudTrail log files contain one or more log entries where each entry is made up of multiple JSON-formatted events. A log entry represents a single request from any source and includes information about the requested action, any parameters, the date and time of the action, and so on. The log entries are not guaranteed to be in any particular order. That is, they are not an ordered stack trace of the public API calls.

The following example shows CloudTrail log entries for the GetFunction and DeleteFunction actions.

{ "Records": [ { "eventVersion": "1.03", "userIdentity": { "type": "IAMUser", "principalId": "A1B2C3D4E5F6G7EXAMPLE", "arn": "arn:aws:iam::999999999999:user/myUserName", "accountId": "999999999999", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "userName": "myUserName" }, "eventTime": "2015-03-18T19:03:36Z", "eventSource": "lambda.amazonaws.com", "eventName": "GetFunction", "awsRegion": "us-east-1", "sourceIPAddress": "", "userAgent": "Python-httplib2/0.8 (gzip)", "errorCode": "AccessDenied", "errorMessage": "User: arn:aws:iam::999999999999:user/myUserName is not authorized to perform: lambda:GetFunction on resource: arn:aws:lambda:us-west-2:999999999999:function:other-acct-function", "requestParameters": null, "responseElements": null, "requestID": "7aebcd0f-cda1-11e4-aaa2-e356da31e4ff", "eventID": "e92a3e85-8ecd-4d23-8074-843aabfe89bf", "eventType": "AwsApiCall", "recipientAccountId": "999999999999" }, { "eventVersion": "1.03", "userIdentity": { "type": "IAMUser", "principalId": "A1B2C3D4E5F6G7EXAMPLE", "arn": "arn:aws:iam::999999999999:user/myUserName", "accountId": "999999999999", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "userName": "myUserName" }, "eventTime": "2015-03-18T19:04:42Z", "eventSource": "lambda.amazonaws.com", "eventName": "DeleteFunction", "awsRegion": "us-east-1", "sourceIPAddress": "", "userAgent": "Python-httplib2/0.8 (gzip)", "requestParameters": { "functionName": "basic-node-task" }, "responseElements": null, "requestID": "a2198ecc-cda1-11e4-aaa2-e356da31e4ff", "eventID": "20b84ce5-730f-482e-b2b2-e8fcc87ceb22", "eventType": "AwsApiCall", "recipientAccountId": "999999999999" } ] }

The eventName may include date and version information, such as "GetFunction20150331", but it is still referring to the same public API. For more information, see Services supported by CloudTrail event history in the AWS CloudTrail User Guide.

Using CloudTrail to track function invocations

CloudTrail also logs data events. You can turn on data event logging so that you log an event every time Lambda functions are invoked. This helps you understand what identities are invoking the functions and the frequency of their invocations. For more information on this option, see Logging data events for trails.


CloudTrail logs only authenticated and authorized requests. CloudTrail does not log requests that fail authentication (credentials are missing or the provided credentials are not valid) or requests with credentials that are not authorized to invoke the function.

Using CloudTrail to troubleshoot disabled event sources

One data event that can be encountered is a LambdaESMDisabled event. There are five general categories of error that are associated with this event:


The resource specified in the request does not exist.


The function attached to the event source does not exist.


A Region name provided to the event source or function is invalid.


Permissions have not been set, or are misconfigured.


The function code does not compile, has encountered an unrecoverable exception, or a bad deployment has occurred.

These errors are included in the CloudTrail event message within the serviceEventDetails entity.

Example serviceEventDetails entity

"serviceEventDetails":{ "ESMDisableReason":"Lambda Function not found" }