Accessing CloudWatch Logs Accessing file system logs Default logging configuration Configure logging for Amazon IoT Greengrass Logging limitations CloudTrail logs

Amazon IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. After this date, Amazon IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on Amazon IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

Monitoring with Amazon IoT Greengrass logs

Amazon IoT Greengrass consists of the cloud service and the Amazon IoT Greengrass Core software. The Amazon IoT Greengrass Core software can write logs to Amazon CloudWatch and to the local file system of your core device. Lambda functions and connectors running on the core can also write logs to CloudWatch Logs and the local file system. You can use logs to monitor events and troubleshoot issues. All Amazon IoT Greengrass log entries include a timestamp, log level, and information about the event. Changes to logging settings take effect after you deploy the group.

Logging is configured at the group level. For steps that show how to configure logging for a Greengrass group, see Configure logging for Amazon IoT Greengrass.

Accessing CloudWatch Logs

If you configure CloudWatch logging, you can view the logs on the Logs page of the Amazon CloudWatch console. Log groups for Amazon IoT Greengrass logs use the following naming conventions:


/aws/greengrass/GreengrassSystem/greengrass-system-component-name
/aws/greengrass/Lambda/aws-region/account-id/lambda-function-name

Each log group contains log streams that use the following naming convention:


date/account-id/greengrass-group-id/name-of-core-that-generated-log

The following considerations apply when you use CloudWatch Logs:

Logs are sent to CloudWatch Logs with a limited number of retries in case there's no internet connectivity. After the retries are exhausted, the event is dropped.
Transaction, memory, and other limitations apply. For more information, see Logging limitations.
Your Greengrass group role must allow Amazon IoT Greengrass to write to CloudWatch Logs. To grant permissions, embed the following inline policy in your group role.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents",
                "logs:DescribeLogStreams"
            ],
            "Resource": [
                "arn:aws:logs:*:*:*"
            ]
        }
    ]
}
```
Note
You can grant more granular access to your log resources. For more information, see Using identity-based policies (IAM policies) for CloudWatch Logs in the Amazon CloudWatch User Guide.

The group role is an IAM role that you create and attach to your Greengrass group. You can use the console or the Amazon IoT Greengrass API to manage the group role.
Using the console
In the Amazon IoT console navigation pane, under Manage, expand Greengrass devices, and then choose Groups (V1).
Choose the target group.

Choose View settings. Under Group role, you can view, associate, or disassociate the group role.

For steps that show you how to attach the group role, see group role.
Using the CLI
To find the group role, use the get-associated-role command.

To attach the group role, use the associate-role-to-group command.

To remove the group role, use the disassociate-role-from-group command.
To learn how to get the group ID to use with these commands, see Getting the group ID.

Accessing file system logs

If you configure file system logging, the log files are stored under greengrass-root/ggc/var/log on the core device. The following is the high-level directory structure:


greengrass-root/ggc/var/log
    - crash.log
    - system
        - log files for each Greengrass system component
    - user
        - region
            - account-id
                - log files generated by each user-defined Lambda function
            - aws
                - log files generated by each connector

Note

By default, greengrass-root is the /greengrass directory. If a write directory is configured, then the logs are under that directory.

The following considerations apply when you use file system logs:

Reading Amazon IoT Greengrass logs on the file system requires root permissions.
Amazon IoT Greengrass supports size-based rotation and automatic cleanup when the amount of log data is close to the configured limit.
The crash.log file is available in file system logs only. This log isn't written to CloudWatch Logs.
Disk usage limitations apply. For more information, see Logging limitations.

Note

Logs for Amazon IoT Greengrass Core software v1.0 are stored under the greengrass-root/var/log directory.

Default logging configuration

If logging settings aren't explicitly configured, Amazon IoT Greengrass uses the following default logging configuration after the first group deployment.

Amazon IoT Greengrass System Components

Type - FileSystem
Component - GreengrassSystem
Level - INFO
Space - 128 KB

User-defined Lambda Functions

Type - FileSystem
Component - Lambda
Level - INFO
Space - 128 KB

Note

Before the first deployment, only system components write logs to the file system because no user-defined Lambda functions are deployed.

Configure logging for Amazon IoT Greengrass

You can use the Amazon IoT console or the Amazon IoT Greengrass APIs to configure Amazon IoT Greengrass logging.

Note

To allow Amazon IoT Greengrass to write logs to CloudWatch Logs, your group role must allow the required CloudWatch Logs actions.

Configure logging (console)

You can configure logging on the group's Settings page.

In the Amazon IoT console navigation pane, under Manage, expand Greengrass devices, and then choose Groups (V1).
Choose the group where you want to configure logging.
On the group configuration page, choose the Logs tab.
Choose the logging location, as follows:
- To configure CloudWatch logging, for CloudWatch logs configuration, choose Edit.
- To configure file system logging, for Local logs configuration, choose Edit.
You can configure logging for one location or both locations.
In the edit logs configuration modal, select Greengrass system log level or User Lambda functions log level. You can choose one component or both components.
Choose the lowest level of events that you want to log. Events below this threshold are filtered out and aren't stored.
Choose Save. Changes take effect after you deploy the group.

Configure logging (API)

You can use Amazon IoT Greengrass logger APIs to configure logging programmatically. For example, use the CreateLoggerDefinition action to create a logger definition based on a LoggerDefinitionVersion payload, which uses the following syntax:


{
  "Loggers": [
    {
      "Id": "string",
      "Type": "FileSystem|AWSCloudWatch",
      "Component": "GreengrassSystem|Lambda",
      "Level": "DEBUG|INFO|WARN|ERROR|FATAL",
      "Space": "integer"
    },
    {
      "Id": "string",
      ...
    }
  ]
}

LoggerDefinitionVersion is an array of one or more Logger objects that have the following properties:

Id

An identifier for the logger.

Type

The storage mechanism for log events. When AWSCloudWatch is used, log events are sent to CloudWatch Logs. When FileSystem is used, log events are stored on the local file system.

Valid values: AWSCloudWatch, FileSystem

Component

The source of the log event. When GreengrassSystem is used, events from Greengrass system components are logged. When Lambda is used, events from user-defined Lambda functions are logged.

Valid values: GreengrassSystem, Lambda

Level

The log-level threshold. Log events below this threshold are filtered out and aren't stored.

Valid values: DEBUG, INFO (recommended), WARN, ERROR, FATAL

Space

The maximum amount of local storage, in KB, to use for storing logs. This field applies only when Type is set to FileSystem.

Configuration example

The following LoggerDefinitionVersion example specifies a logging configuration that:

Turns on file system ERROR and above logging for Amazon IoT Greengrass system components.
Turns on file system INFO (and above) logging for user-defined Lambda functions.
Turns on CloudWatch INFO (and above) logging for user-defined Lambda functions.


{
  "Name": "LoggingExample",
  "InitialVersion": {
    "Loggers": [
      {
        "Id": "1",
        "Component": "GreengrassSystem",
        "Level": "ERROR",
        "Space": 10240,
        "Type": "FileSystem"
      },
      {
        "Id": "2",
        "Component": "Lambda",
        "Level": "INFO",
        "Space": 10240,
        "Type": "FileSystem"
      },
      {
        "Id": "3",
        "Component": "Lambda",
        "Level": "INFO",
        "Type": "AWSCloudWatch"
      }
    ]
  }
}

After you create a logger definition version, you can use its version ARN to create a group version before deploying the group.

Logging limitations

Amazon IoT Greengrass has the following logging limitations.

Transactions per second

When logging to CloudWatch is enabled, the logging component batches log events locally before sending them to CloudWatch, so you can log at a rate higher than five requests per second per log stream.

Memory

If Amazon IoT Greengrass is configured to send logs to CloudWatch and a Lambda function logs more than 5 MB/second for a prolonged period of time, the internal processing pipeline eventually fills up. The theoretical worst case is 6 MB per Lambda function.

Clock skew

When logging to CloudWatch is enabled, the logging component signs requests to CloudWatch using the normal Signature Version 4 signing process. If the system time on the Amazon IoT Greengrass core device is out of sync by more than 15 minutes, then the requests are rejected.

Disk usage

Use the following formula to calculate the total maximum amount of disk usage for logging.


greengrass-system-component-space * 8    // 7 if automatic IP detection is disabled
  + 128KB                                // the internal log for the local logging component
  + lambda-space * lambda-count          // different versions of a Lambda function are treated as one

Where:

greengrass-system-component-space: The maximum amount of local storage for the Amazon IoT Greengrass system component logs.
lambda-space: The maximum amount of local storage for Lambda function logs.
lambda-count: The number of deployed Lambda functions.

Log loss

If your Amazon IoT Greengrass core device is configured to log only to CloudWatch and there's no internet connectivity, you have no way to retrieve the logs currently in the memory.

When Lambda functions are terminated (for example, during deployment), a few seconds' worth of logs are not written to CloudWatch.

CloudTrail logs

Amazon IoT Greengrass runs with Amazon CloudTrail, a service that provides a record of actions taken by a user, role, or an Amazon service in Amazon IoT Greengrass. For more information, see Logging Amazon IoT Greengrass API calls with Amazon CloudTrail.

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Logging and monitoring

Logging Amazon IoT Greengrass API calls with Amazon CloudTrail