Log Amazon IoT Greengrass V2 API calls with Amazon CloudTrail - Amazon IoT Greengrass
Amazon IoT Greengrass V2 information in CloudTrailAmazon IoT Greengrass data events in CloudTrailAmazon IoT Greengrass management events in CloudTrailUnderstanding Amazon IoT Greengrass V2 log file entries
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Log Amazon IoT Greengrass V2 API calls with Amazon CloudTrail

Amazon IoT Greengrass V2 is integrated with Amazon CloudTrail, a service that provides a record of actions taken by a user, role, or an Amazon service in Amazon IoT Greengrass Version 2. CloudTrail captures all API calls for Amazon IoT Greengrass as events. The calls that are captured include calls from the Amazon IoT Greengrass console and code calls to the Amazon IoT Greengrass API operations.

If you create a trail, you can enable continuous delivery of CloudTrail events to an S3 bucket, including events for Amazon IoT Greengrass. 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 Amazon IoT Greengrass, the IP address from which the request was made, who made the request, when it was made, and additional details.

For more information about CloudTrail, see the Amazon CloudTrail User Guide.

Amazon IoT Greengrass V2 information in CloudTrail

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

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

All Amazon IoT Greengrass V2 actions are logged by CloudTrail and are documented in the Amazon IoT Greengrass V2 API Reference. For example, calls to the CreateComponentVersion, CreateDeployment and CancelDeployment actions generate entries in the CloudTrail log files.

Every event or log entry contains information about who generated the request. The identity information helps you determine the following:

  • Whether the request was made with root or Amazon Identity and Access Management (IAM) user credentials.

  • Whether the request was made with temporary security credentials for a role or federated user.

  • Whether the request was made by another Amazon service.

For more information, see the CloudTrail userIdentity element.

Amazon IoT Greengrass data events in CloudTrail

Data events provide information about the resource operations performed on or in a resource (for example, getting a component version or the configuration of a deployment). These are also known as data plane operations. Data events are often high-volume activities. By default, CloudTrail doesn’t log data events. The CloudTrail Event history doesn't record data events.

Additional charges apply for data events. For more information about CloudTrail pricing, see Amazon CloudTrail Pricing.

You can log data events for the Amazon IoT Greengrass resource types by using the CloudTrail console, Amazon CLI, or CloudTrail API operations. The table in this section shows the resource types available for Amazon IoT Greengrass.

  • To log data events using the CloudTrail console, create a trail or event data store to log data events, or update an existing trail or event data store to log data events.

    1. Choose Data events to log data events.

    2. From the Data event type list, choose the resource type for which you want to log data events.

    3. Choose the log selector template you want to use. You can log all data events for the resource type, log all readOnly events, log all writeOnly events, or create a custom log selector template to filter on the readOnly, eventName, and resources.ARN fields.

  • To log data events using the Amazon CLI, configure the --advanced-event-selectors parameter to set the eventCategory field equal to Data and the resources.type field equal to the resource type value (see table). You can add conditions to filter on the values of the readOnly, eventName, and resources.ARN fields.

The following table lists the Amazon IoT Greengrass resource types. The Data event type (console) column shows the value to choose from the Data event type list on the CloudTrail console. The resources.type value column shows the resources.type value, which you would specify when configuring advanced event selectors using the Amazon CLI or CloudTrail APIs. The Data APIs logged to CloudTrail column shows the API calls logged to CloudTrail for the resource type.

Data event type (console) resources.type value Data APIs logged to CloudTrail
IoT certificate AWS::IoT::Certificate

  • VerifyClientDeviceIdentity

  • VerifyClientDeviceIoTCertificateAssociation
IoT Greengrass component version AWS::GreengrassV2::ComponentVersion
IoT Greengrass deployment AWS::GreengrassV2::Deployment

  • GetDeploymentConfiguration
IoT thing AWS::IoT::Thing

  • ListThingGroupsForCoreDevices

  • PutCertificateAuthorities

  • VerifyClientDeviceIoTCertificateAssociation

You can configure advanced event selectors to filter on the eventName, readOnly, and resources.ARN fields to log only those events that are important to you.

Add a filter on eventName to include or exclude specific data APIs.

For more information about these fields, see AdvancedFieldSelector.

The following examples show how to configure advanced selectors using the Amazon CLI. Replace TrailName and region with your own information.

Example – Log data events for IoT things
aws cloudtrail put-event-selectors --trail-name TrailName --region region \
--advanced-event-selectors \
‘[
    {
            “Name”: “Log all thing data events”,
            “FieldSelectors”: [
                { “Field”: “eventCategory”, “Equals”: [“Data”] },
                { “Field”: “resources.type”, “Equals”: [“AWS::IoT::Thing”] }
            ]
        }
]’
Example – Filter on a specific IoT thing API
aws cloudtrail put-event-selectors --trail-name TrailName --region region \
--advanced-event-selectors \
‘[
    {
            “Name”: “Log IoT Greengrass PutCertificateAuthorities API calls”,
            “FieldSelectors”: [
                { “Field”: “eventCategory”, “Equals”: [“Data”] },
                { “Field”: “resources.type”, “Equals”: [“AWS::IoT::Thing”] },
                { “Field”: “eventName”, “Equals”: [“PutCertificateAuthorities”] }
            ]
    }
]’
Example – Log all Greengrass data events
aws cloudtrail put-event-selectors --trail-name TrailName --region region \
--advanced-event-selectors \
‘[
    {
        “Name”: “Log all certificate data events”,
        “FieldSelectors”: [
            {
                “Field”: “eventCategory”,
                “Equals”: [
                    “Data”
                ]
            },
            {
                “Field”: “resources.type”,
                “Equals”: [
                    “AWS::IoT::Certificate”
                ]
            }
        ]
    },
    {
        “Name”: “Log all component version data events”,
        “FieldSelectors”: [
            {
                “Field”: “eventCategory”,
                “Equals”: [
                    “Data”
                ]
            },
            {
                “Field”: “resources.type”,
                “Equals”: [
                    “AWS::GreengrassV2::ComponentVersion”
                ]
            }
        ]
    },
    {
        “Name”: “Log all deployment version”,
        “FieldSelectors”: [
            {
                “Field”: “eventCategory”,
                “Equals”: [
                    “Data”
                ]
            },
            {
                “Field”: “resources.type”,
                “Equals”: [
                    “AWS::GreengrassV2::Deployment”
                ]
            }
        ]
    },
    {
        “Name”: “Log all thing data events”,
        “FieldSelectors”: [
            {
                “Field”: “eventCategory”,
                “Equals”: [
                    “Data”
                ]
            },
            {
                “Field”: “resources.type”,
                “Equals”: [
                    “AWS::IoT::Thing”
                ]
            }
        ]
    }
]’

Amazon IoT Greengrass management events in CloudTrail

Management events provide information about management operations that are performed on resources in your Amazon account. These are also known as control plane operations. By default, CloudTrail logs management events.

Amazon IoT Greengrass logs all Amazon IoT Greengrass control plane operations as management events. For a list of the Amazon IoT Greengrass control plane operations that Amazon IoT Greengrass logs to CloudTrail, see the Amazon IoT Greengrass API reference, version 2.

Understanding Amazon IoT Greengrass V2 log file entries

A trail is a configuration that enables delivery of events as log files to an S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source. It includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files aren't an ordered stack trace of the public API calls, so they don't appear in any specific order.

The following example shows a CloudTrail log entry that demonstrates the CreateDeployment action.

{
    "eventVersion": "1.08",
    "userIdentity": {
        "type": "IAMUser",
        "principalId": "AIDACKCEVSQ6C2EXAMPLE",
        "arn": "arn:aws-cn:iam::123456789012:user/Administrator",
        "accountId": "123456789012",
        "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
        "userName": "Administrator"
    },
    "eventTime": "2021-01-06T02:38:05Z",
    "eventSource": "greengrass.amazonaws.com",
    "eventName": "CreateDeployment",
    "awsRegion": "us-west-2",
    "sourceIPAddress": "203.0.113.0",
    "userAgent": "aws-cli/2.1.9 Python/3.7.9 Windows/10 exe/AMD64 prompt/off command/greengrassv2.create-deployment",
    "requestParameters": {
        "deploymentPolicies": {
            "failureHandlingPolicy": "DO_NOTHING",
            "componentUpdatePolicy": {
                "timeoutInSeconds": 60,
                "action": "NOTIFY_COMPONENTS"
            },
            "configurationValidationPolicy": {
                "timeoutInSeconds": 60
            }
        },
        "deploymentName": "Deployment for MyGreengrassCoreGroup",
        "components": {
            "aws.greengrass.Cli": {
                "componentVersion": "2.0.3"
            }
        },
        "iotJobConfiguration": {},
        "targetArn": "arn:aws-cn:iot:us-west-2:123456789012:thinggroup/MyGreengrassCoreGroup"
    },
    "responseElements": {
        "iotJobArn": "arn:aws-cn:iot:us-west-2:123456789012:job/fdfeba1d-ac6d-44ef-ab28-54f684ea578d",
        "iotJobId": "fdfeba1d-ac6d-44ef-ab28-54f684ea578d",
        "deploymentId": "4196dddc-0a21-4c54-a985-66a525f6946e"
    },
    "requestID": "311b9529-4aad-42ac-8408-c06c6fec79a9",
    "eventID": "c0f3aa2c-af22-48c1-8161-bad4a2ab1841",
    "readOnly": false,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "eventCategory": "Management",
    "recipientAccountId": "123456789012"
}