# Logging and monitoring in AWS IoT Greengrass Monitoring is an important part of maintaining the reliability, availability, and performance of AWS IoT Greengrass and your AWS solutions. You should collect monitoring data from all parts of your AWS solution so that you can more easily debug a multi-point failure, if one occurs. Before you start monitoring AWS IoT Greengrass, you should create a monitoring plan that includes answers to the following questions: + What are your monitoring goals? + Which resources will you monitor? + How often will you monitor these resources? + Which monitoring tools will you use? + Who will perform the monitoring tasks? + Who should be notified when something goes wrong? **Topics** + [Monitoring tools](#monitoring-tools) + [Monitor AWS IoT Greengrass logs](monitor-logs.md) + [Log AWS IoT Greengrass V2 API calls with AWS CloudTrail](logging-using-cloudtrail.md) + [Gather system health telemetry data from AWS IoT Greengrass core devices](telemetry.md) + [Get deployment and component health status notifications](deployment-health-notifications.md) + [Check Greengrass core device status](device-status.md) ## Monitoring tools AWS provides tools that you can use to monitor AWS IoT Greengrass. You can configure some of these tools to do the monitoring for you. Some of the tools require manual intervention. We recommend that you automate monitoring tasks as much as possible. You can use the following automated monitoring tools to monitor AWS IoT Greengrass and report issues: + **Amazon CloudWatch Logs** – Monitor, store, and access your log files from AWS CloudTrail or other sources. For more information, see [Monitoring log files](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatchLogs.html) in the *Amazon CloudWatch User Guide*. + **AWS CloudTrail Log Monitoring** – Share log files between accounts, monitor CloudTrail log files in real time by sending them to CloudWatch Logs, write log processing applications in Java, and validate that your log files have not changed after delivery by CloudTrail. For more information, see [Working with CloudTrail log files](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html) in the *AWS CloudTrail User Guide*. + **Greengrass system health telemetry** – Subscribe to receive telemetry data sent from the Greengrass core. For more information, see [Gather system health telemetry data from AWS IoT Greengrass core devices](telemetry.md). + **Device health notifications** Create events using Amazon EventBridge to receive status updates regarding deployments and components. For more information, see [Get deployment and component health status notifications](deployment-health-notifications.md). + **Fleet status service** – Use the fleet status API operations to check the status of core devices and their Greengrass components. You can also view fleet status information in the AWS IoT Greengrass console. For more information, see [Check Greengrass core device status](device-status.md). # Monitor AWS IoT Greengrass logs AWS IoT Greengrass consists of the cloud service and the AWS IoT Greengrass Core software. The AWS IoT Greengrass Core software can write logs to Amazon CloudWatch Logs and to the core device's local file system. Greengrass components that run on the core device can also write logs to CloudWatch Logs and the local file system. You can use logs to monitor events and troubleshoot issues. All AWS IoT Greengrass log entries include a timestamp, log level, and information about the event. By default, the AWS IoT Greengrass Core software writes logs to only the local file system. You can view file system logs in real time, so you can debug Greengrass components that you develop and deploy. You can also configure a core device to write logs to CloudWatch Logs, so you can troubleshoot the core device without access to the local file system. For more information, see [Enable logging to CloudWatch Logs](#enable-cloudwatch-logs). **Topics** + [Access file system logs](#access-local-logs) + [Access CloudWatch Logs](#access-cloudwatch-logs) + [Access system service logs](#access-system-service-logs) + [Enable logging to CloudWatch Logs](#enable-cloudwatch-logs) + [Configure logging for AWS IoT Greengrass](#configure-logging) + [AWS CloudTrail logs](#cloudtrail-integration) ## Access file system logs The AWS IoT Greengrass Core software stores logs in the `/greengrass/v2/logs` folder on a core device, where `/greengrass/v2` is the path to the AWS IoT Greengrass root folder. The logs folder has the following structure. ``` /greengrass/v2 └── logs ├── greengrass.log ├── greengrass_2021_09_14_15_0.log ├── ComponentName.log ├── ComponentName_2021_09_14_15_0.log └── main.log ``` + `greengrass.log` – The AWS IoT Greengrass Core software log file. Use this log file to view real-time information about components and deployments. This log file includes logs for the Greengrass nucleus, which is the core of the AWS IoT Greengrass Core software, and plugin components, such as [log manager](log-manager-component.md) and [secret manager](secret-manager-component.md). + `ComponentName.log` – Greengrass component log files. Use component log files to view real-time information about a Greengrass component that runs on the core device. Generic components and Lambda components write standard output (stdout) and standard error (stderr) to these log files. + `main.log` – The log file for the `main` service that handles component lifecycles. This log file will always be empty. For more information about the differences between plugin, generic, and Lambda components, see [Component types](develop-greengrass-components.md#component-types). The following considerations apply when you use file system logs: + **Root user permissions** You must have root permissions to read AWS IoT Greengrass logs on the file system. + **Log file rotation** The AWS IoT Greengrass Core software rotates log files every hour or when they exceed a file size limit. Rotated log files contain a timestamp in their file name. For example, a rotated AWS IoT Greengrass Core software log file might be named `greengrass_2021_09_14_15_0.log`. The default file size limit is 1,024 KB (1 MB). You can configure the file size limit on the [Greengrass nucleus component](greengrass-nucleus-component.md). + **Log file deletion** The AWS IoT Greengrass Core software cleans up earlier log files when the size of AWS IoT Greengrass Core software log files or Greengrass component log files, including rotated log files, exceeds a disk space limit. The default disk space limit for the AWS IoT Greengrass Core software log and each component log is 10,240 KB (10 MB). You can configure the AWS IoT Greengrass Core software log disk space limit on the [Greengrass nucleus component](greengrass-nucleus-component.md) or the [log manager component](log-manager-component.md). You can configure each component's log disk space limit on the [log manager component](log-manager-component.md). **To view the AWS IoT Greengrass Core software log file** + Run the following command to view the log file in real time. Replace `/greengrass/v2` with the path to the AWS IoT Greengrass root folder. ------ #### [ Linux or Unix ] ``` sudo tail -f /greengrass/v2/logs/greengrass.log ``` ------ #### [ Windows Command Prompt (CMD) ] ``` type C:\greengrass\v2\logs\com.example.HelloWorld.log ``` The `type` command writes the file's contents to the terminal. Run this command multiple times to observe changes in the file. ------ #### [ PowerShell ] ``` gc C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait ``` ------ **To view the log file for a component** + Run the following command to view the log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder, and replace *com.example.HelloWorld* with the name of the component. ------ #### [ Linux or Unix ] ``` sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log ``` ------ #### [ PowerShell ] ``` gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait ``` ------ You can also use the `logs` command of the [Greengrass CLI](greengrass-cli-component.md) to analyze Greengrass logs on a core device. To use the `logs` command, you must configure the [Greengrass nucleus](greengrass-nucleus-component.md) to output JSON format log files. For more information, see [Greengrass Command Line Interface](gg-cli.md) and [logs](gg-cli-logs.md). ## Access CloudWatch Logs You can deploy the [log manager component](log-manager-component.md) to configure the core device to write to CloudWatch Logs. For more information, see [Enable logging to CloudWatch Logs](#enable-cloudwatch-logs). Then, you can view logs on the **Logs** page of the Amazon CloudWatch console or using the CloudWatch Logs API. **Log group name** ``` /aws/greengrass/componentType/region/componentName ``` The log group name uses the following variables: + `componentType` – The type of the component, which can be one of the following: + `GreengrassSystemComponent` – This log group includes logs for the nucleus and plugin components, which run in the same JVM as the Greengrass nucleus. The component is part of the [Greengrass nucleus](greengrass-nucleus-component.md). + `UserComponent` – This log group includes logs for generic components, Lambda components, and other applications on the device. The component isn't part of the Greengrass nucleus. For more information, see [Component types](develop-greengrass-components.md#component-types). + `region` – The AWS Region that the core device uses. + `componentName` – The name of the component. For system logs, this value is `System`. **Log stream name** ``` /date/thing/thingName ``` The log stream name uses the following variables: + `date` – The date of the log, such as `2020/12/15`. The log manager component uses the `yyyy/MM/dd` format. + `thingName` – The name of the core device. If a thing name contains a colon (`:`), the log manager replaces the colon with a plus (`+`). The following considerations apply when you use the log manager component to write to CloudWatch Logs: + **Log delays** **Note** We recommend that you upgrade to log manager version 2.3.0 which reduces log delays for rotated and active log files. When you upgrade to log manager 2.3.0, we recommend you also upgrade to Greengrass nucleus 2.9.1. The log manager component version 2.2.8 (and earlier) processes and uploads logs from only rotated log files. By default, the AWS IoT Greengrass Core software rotates log files every hour or after they are 1,024 KB. As a result, the log manager component uploads logs only after the AWS IoT Greengrass Core software or a Greengrass component writes over 1,024 KB worth of logs. You can configure a lower log file size limit to cause log files to rotate more often. This causes the log manager component to upload logs to CloudWatch Logs more frequently. The log manager component version 2.3.0 (and later) processes and uploads all logs. When you write a new log, log manager version 2.3.0 (and later) processes and directly uploads that active log file instead of waiting for it to be rotated. This means that you can view the new log in 5 minutes or less. The log manager component uploads new logs periodically. By default, the log manager component uploads new logs every 5 minutes. You can configure a lower upload interval, so the log manager component uploads logs to CloudWatch Logs more frequently by configuring the `periodicUploadIntervalSec`. For more information about how to configure this periodic interval, see [Configuration](https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html#log-manager-component-configuration). Logs can be uploaded in near real-time from the same Greengrass file system. If you need to observe logs in real time, consider using [file system logs](#access-local-logs). **Note** If you're using different file systems to write logs to, log manager reverts back to the behavior in log manager component versions 2.2.8 and earlier. For information about accessing file system logs, see [Access file system logs](https://docs.aws.amazon.com/greengrass/v2/developerguide/monitor-logs.html#access-local-logs). + **Clock skew** The log manager component uses the standard Signature Version 4 signing process to create API requests to CloudWatch Logs. If the system time on a core device is out of sync by more than 15 minutes, then CloudWatch Logs rejects the requests. For more information, see [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) in the *AWS General Reference*. ## Access system service logs If you [configure the AWS IoT Greengrass Core software as a system service](configure-greengrass-core-v2.md#configure-system-service), you can view system service logs to troubleshoot issues, such as the software failing to start. **To view system service logs (CLI)** 1. Run the following command to view AWS IoT Greengrass Core software system service logs. ------ #### [ Linux or Unix (systemd) ] ``` sudo journalctl -u greengrass.service ``` ------ #### [ Windows Command Prompt (CMD) ] ``` type C:\greengrass\v2\logs\greengrass.wrapper.log ``` ------ #### [ PowerShell ] ``` gc C:\greengrass\v2\logs\greengrass.wrapper.log ``` ------ 1. On Windows devices, the AWS IoT Greengrass Core software creates a separate log file for system service errors. Run the following command to view the system service error logs. ------ #### [ Windows Command Prompt (CMD) ] ``` type C:\greengrass\v2\logs\greengrass.err.log ``` ------ #### [ PowerShell ] ``` gc C:\greengrass\v2\logs\greengrass.err.log ``` ------ On Windows devices, you can also use the **Event Viewer** application to view system service logs. **To view Windows service logs (Event Viewer)** 1. Open the **Event Viewer** application. 1. Select **Windows Logs** to expand it. 1. Choose **Application** to view application service logs. 1. Find and open event logs whose **Source** is **greengrass**. ## Enable logging to CloudWatch Logs You can deploy the [log manager component](log-manager-component.md) to configure a core device to write logs to CloudWatch Logs. You can enable CloudWatch Logs for AWS IoT Greengrass Core software logs, and you can enable CloudWatch Logs for specific Greengrass components. **Note** The Greengrass core device's token exchange role must allow the core device to write to CloudWatch Logs, as shown in the following example IAM policy. If you [installed the AWS IoT Greengrass Core software with automatic resource provisioning](quick-installation.md), your core device has these permissions. ``` { "Version": "2012-10-17", "Statement": [ { "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams" ], "Effect": "Allow", "Resource": "arn:aws:logs:*:*:*" } ] } ``` To configure a core device to write AWS IoT Greengrass Core software logs to CloudWatch Logs, [create a deployment](create-deployments.md) that specifies a configuration update that sets `uploadToCloudWatch` to `true` for the `aws.greengrass.LogManager` component. AWS IoT Greengrass Core software logs include logs for the [Greengrass nucleus](greengrass-nucleus-component.md) and [plugin components](develop-greengrass-components.md#component-types). ``` { "logsUploaderConfiguration": { "systemLogsConfiguration": { "uploadToCloudWatch": "true" } } } ``` To configure a core device to write a Greengrass component's logs to CloudWatch Logs, [create a deployment](create-deployments.md) that specifies a configuration update that adds the component to the list of component logging configurations. When you add a component to this list, the log manager component writes its logs to CloudWatch Logs. Component logs include logs for [generic components and Lambda components](develop-greengrass-components.md#component-types). ``` { "logsUploaderConfiguration": { "componentLogsConfigurationMap": { "com.example.HelloWorld": { } } } } ``` When you deploy the log manager component, you can also configure disk space limits and whether the core device deletes log files after writing them to CloudWatch Logs. For more information, see [Configure logging for AWS IoT Greengrass](#configure-logging). ## Configure logging for AWS IoT Greengrass You can configure the following options to customize logging for Greengrass core devices. To configure these options, [create a deployment](create-deployments.md) that specifies a configuration update to the Greengrass nucleus or log manager components. + **Writing logs to CloudWatch Logs** To remotely troubleshoot core devices, you can configure core devices to write AWS IoT Greengrass Core software and component logs to CloudWatch Logs. To do so, deploy and configure the [log manager component](log-manager-component.md). For more information, see [Enable logging to CloudWatch Logs](#enable-cloudwatch-logs). + **Deleting uploaded log files** To reduce disk space usage, you can configure core devices to delete log files after writing the log files to CloudWatch Logs. For more information, see the log manager component's `deleteLogFileAfterCloudUpload` parameter, which you can specify for [AWS IoT Greengrass Core software logs](log-manager-component.md#log-manager-component-configuration-system-logs-configuration) and [component logs](log-manager-component.md#log-manager-component-configuration-component-logs-configuration). + **Log disk space limits** To limit disk space usage, you can configure the maximum disk space for each log, including its rotated log files, on a core device. For example, you can configure the maximum combined disk space for `greengrass.log` and rotated `greengrass.log` files. For more information, see the Greengrass nucleus component's `logging.totalLogsSizeKB` parameter and the log manager component's `diskSpaceLimit` parameter, which you can specify for [AWS IoT Greengrass Core software logs](log-manager-component.md#log-manager-component-configuration-system-logs-configuration) and [component logs](log-manager-component.md#log-manager-component-configuration-component-logs-configuration). + **Log file size limit** You can configure the maximum file size for each log file. After a log file exceeds this file size limit, the AWS IoT Greengrass Core software creates a new log file. The [log manager component](log-manager-component.md) version 2.28 (and earlier) writes only rotated log files to CloudWatch Logs, so you can specify a lower file size limit to write logs to CloudWatch Logs more frequently. The log manager component version 2.3.0 (and later) processes and uploads all logs instead of waiting for them to be rotated. For more information, see the Greengrass nucleus component's [log file size limit parameter](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-log-file-size) (`logging.fileSizeKB`). + **Minimum log levels** You can configure the minimum log level that the Greengrass nucleus component writes to file system logs. For example, you might specify `DEBUG` level logs to help with troubleshooting, or you might specify `ERROR` level logs to reduce the amount of logs that a core device creates. For more information, see the Greengrass nucleus component's [log level parameter](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-log-level) (`logging.level`). You can also configure the minimum log level that the log manager component writes to CloudWatch Logs. For example, you might specify a higher log level to reduce [logging costs](https://aws.amazon.com/cloudwatch/pricing/). For more information, see the log manager component's `minimumLogLevel` parameter, which you can specify for [AWS IoT Greengrass Core software logs](log-manager-component.md#log-manager-component-configuration-system-logs-configuration) and [component logs](log-manager-component.md#log-manager-component-configuration-component-logs-configuration). + **Interval to check for logs to write to CloudWatch Logs** To increase or decrease how frequently the log manager component writes logs to CloudWatch Logs, you can configure the interval where it checks for new log files to write. For example, you might specify a lower interval to view logs in CloudWatch Logs sooner than you would with the default 5-minute interval. You might specify a higher interval to reduce costs, because the log manager component batches log files into fewer requests. For more information, see the log manager component's [upload interval parameter](log-manager-component.md#log-manager-component-configuration-periodic-upload-interval-sec) (`periodicUploadIntervalSec`). + **Log format** You can choose whether the AWS IoT Greengrass Core software writes logs in text or JSON format. Choose text format if you read logs, or choose JSON format if you use an application to read or parse logs. For more information, see the Greengrass nucleus component's [log format parameter](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) (`logging.format`). + **Local file system logs folder** You can change the logs folder from `/greengrass/v2/logs` to another folder on the core device. For more information, see the Greengrass nucleus component's [output directory parameter](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-log-level) (`logging.outputDirectory`). ## AWS CloudTrail logs AWS IoT Greengrass integrates with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or AWS service in AWS IoT Greengrass. For more information, see [Log AWS IoT Greengrass V2 API calls with AWS CloudTrail](logging-using-cloudtrail.md). # Log AWS IoT Greengrass V2 API calls with AWS CloudTrail AWS IoT Greengrass V2 is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in AWS IoT Greengrass Version 2. CloudTrail captures all API calls for AWS IoT Greengrass as events. The calls that are captured include calls from the AWS IoT Greengrass console and code calls to the AWS IoT Greengrass API operations. If you create a trail, you can enable continuous delivery of CloudTrail events to an S3 bucket, including events for AWS 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 AWS 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 [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html). **Topics** + [AWS IoT Greengrass V2 information in CloudTrail](#service-name-info-in-cloudtrail) + [AWS IoT Greengrass data events in CloudTrail](#greengrass-data-events-cloudtrail) + [AWS IoT Greengrass management events in CloudTrail](#greengrass-management-events-cloudtrail) + [Understanding AWS IoT Greengrass V2 log file entries](#understanding-service-name-entries) ## AWS IoT Greengrass V2 information in CloudTrail CloudTrail is enabled on your AWS account when you create the account. When activity occurs in AWS IoT Greengrass, 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](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html). For an ongoing record of events in your AWS account, including events for AWS 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 AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the 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: + [Overview for creating a trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) + [CloudTrail supported services and integrations](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html) + [Configuring Amazon SNS notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/configure-sns-notifications-for-cloudtrail.html) + [Receiving CloudTrail log files from multiple regions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) and [Receiving CloudTrail log files from multiple accounts](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html) All AWS IoT Greengrass V2 actions are logged by CloudTrail and are documented in the [AWS IoT Greengrass V2 API Reference](https://docs.aws.amazon.com/greengrass/v2/APIReference/Welcome.html). 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 AWS 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 AWS service. For more information, see the [CloudTrail userIdentity element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). ## AWS IoT Greengrass data events in CloudTrail [Data events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-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 [AWS CloudTrail Pricing](https://aws.amazon.com/cloudtrail/pricing/). You can log data events for the AWS IoT Greengrass resource types by using the CloudTrail console, AWS CLI, or CloudTrail API operations. The [table](#data-events-table) in this section shows the resource types available for AWS IoT Greengrass. + To log data events using the CloudTrail console, create a [trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-a-trail-using-the-console-first-time.html#creating-a-trail-in-the-console) or [event data store](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-event-data-store-cloudtrail.html) to log data events, or [update an existing trail or event data store](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events-console) to log data events. 1. Choose **Data events** to log data events. 1. From the **Data event type** list, choose the resource type for which you want to log data events. 1. 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 AWS 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](#data-events-table)). You can add conditions to filter on the values of the `readOnly`, `eventName`, and `resources.ARN` fields. + To configure a trail to log data events, run the [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/put-event-selectors.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/put-event-selectors.html) command. For more information, see [Logging data events for trails with the AWS CLI](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events-CLI-trail-examples). + To configure an event data store to log data events, run the [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/create-event-data-store.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/create-event-data-store.html) command to create a new event data store to log data events, or run the [https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/update-event-data-store.html](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/update-event-data-store.html) command to update an existing event data store. For more information, see [Logging data events for event data stores with the AWS CLI](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events-CLI-eds-examples). The following table lists the AWS 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 AWS 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 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/logging-using-cloudtrail.html) | | IoT Greengrass component version | AWS::GreengrassV2::ComponentVersion | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/logging-using-cloudtrail.html) | | IoT Greengrass deployment | AWS::GreengrassV2::Deployment | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/logging-using-cloudtrail.html) | | IoT thing | AWS::IoT::Thing | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/logging-using-cloudtrail.html) | 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 [https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html). The following examples show how to configure advanced selectors using the AWS 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” ] } ] } ]’ ``` ## AWS IoT Greengrass management events in CloudTrail [Management events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html#logging-management-events) provide information about management operations that are performed on resources in your AWS account. These are also known as control plane operations. By default, CloudTrail logs management events. AWS IoT Greengrass logs all AWS IoT Greengrass control plane operations as management events. For a list of the AWS IoT Greengrass control plane operations that AWS IoT Greengrass logs to CloudTrail, see the [AWS IoT Greengrass API reference, version 2](https://docs.aws.amazon.com/greengrass/v2/APIReference/Welcome.html). ## Understanding AWS 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: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:iot:us-west-2:123456789012:thinggroup/MyGreengrassCoreGroup" }, "responseElements": { "iotJobArn": "arn:aws: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" } ``` # Gather system health telemetry data from AWS IoT Greengrass core devices System health telemetry data is diagnostic data that can help you monitor the performance of critical operations on your Greengrass core devices. You can create projects and applications to retrieve, analyze, transform, and report telemetry data from your edge devices. Domain experts, such as process engineers, can use these applications to gain insights into fleet health. You can use the following methods to gather telemetry data from your Greengrass core devices: + **Nucleus telemetry emitter component**—The [nucleus telemetry emitter component](nucleus-emitter-component.md) (`aws.greengrass.telemetry.NucleusEmitter`) on a Greengrass core device publishes telemetry data to the `$local/greengrass/telemetry` topic by default. You can use the data that is published to this topic to act locally on your core device, even when your device has limited connectivity to the cloud. Optionally, you can also configure the component to publish telemetry data to an AWS IoT Core MQTT topic of your choice. You must deploy the nucleus emitter component to a core device to publish telemetry data. There are no costs associated with publishing telemetry data to the local topic. However, the use of an MQTT topic to publish data to the AWS Cloud is subject to [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/). AWS IoT Greengrass provides several [community components](greengrass-software-catalog.md) to help you analyze and visualize telemetry data locally on your core device using InfluxDB and Grafana. These components use telemetry data from the nucleus emitter component. For more information, see the README for the [InfluxDB publisher component](https://github.com/awslabs/aws-greengrass-labs-telemetry-influxdbpublisher). + **Telemetry agent**—The telemetry agent on Greengrass core devices collects local telemetry data and publishes it to Amazon EventBridge without requiring any customer interaction. Core devices publish telemetry data to EventBridge on a best effort basis. For example, core devices might fail to deliver telemetry data while offline. The telemetry agent feature is enabled by default for all Greengrass core devices. You automatically start to receive data as soon as you set up a Greengrass core device. Aside from your data link costs, the data transfer from the core device to AWS IoT Core is without charge. This is because the agent publishes to an AWS reserved topic. However, depending on your use case, you might incur costs when you receive or process the data. **Note** Amazon EventBridge is an event bus service that you can use to connect your applications with data from a variety of sources, such as Greengrass core devices. For more information, see [What is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html) in the *Amazon EventBridge User Guide*. To ensure that the the AWS IoT Greengrass Core software functions properly, AWS IoT Greengrass uses the data for development and quality improvement purposes. This feature also helps inform new and enhanced edge capabilities. AWS IoT Greengrass retains telemetry data for up to seven days. This section describes how to configure and use the telemetry agent. For information about configuring the nucleus telemetry emitter component, see [Nucleus telemetry emitter](nucleus-emitter-component.md). **Topics** + [Telemetry metrics](#telemetry-metrics) + [Configure telemetry agent settings](#configure-telemetry-agent-settings) + [Subscribe to telemetry data in EventBridge](#subscribe-for-telemetry-data) ## Telemetry metrics The following table describes the metrics that are published by the telemetry agent. | Name | Description | | --- | --- | | **System** | | `SystemMemUsage` | The amount of memory currently in use by all applications on the Greengrass core device, including the operating system. | | `CpuUsage` | The amount of CPU currently in use by all applications on the Greengrass core device, including the operating system. | | `TotalNumberOfFDs` | The number of file descriptors stored by the operating system of the Greengrass core device. One file descriptor uniquely identifies one open file. | | **Greengrass nucleus** | | `NumberOfComponentsRunning` | The number of components that are running on the Greengrass core device. | | `NumberOfComponentsErrored` | The number of components that are in error state on the Greengrass core device. | | `NumberOfComponentsInstalled` | The number of components that are installed on the Greengrass core device. | | `NumberOfComponentsStarting` | The number of components that are starting on the Greengrass core device. | | `NumberOfComponentsNew` | The number of components that are new on the Greengrass core device. | | `NumberOfComponentsStopping` | The number of components that are stopping on the Greengrass core device. | | `NumberOfComponentsFinished` | The number of components that are finished on the Greengrass core device. | | `NumberOfComponentsBroken` | The number of components that are broken on the Greengrass core device. | | `NumberOfComponentsStateless` | The number of components that are stateless on the Greengrass core device. | | **Client device auth** – This feature requires v2.4.0 or later of the client device auth component. | | `VerifyClientDeviceIdentity.Success` | The number of times verifying that the client device identity succeeded. | | `VerifyClientDeviceIdentity.Failure` | The number of times verifying that the client device identity failed. | | `AuthorizeClientDeviceActions.Success` | The number of times the client device is authorized to complete requested actions. | | `AuthorizeClientDeviceActions.Failure` | The number of times the client device is not authorized to complete requested actions. | | `GetClientDeviceAuthToken.Success` | The number of times the client device is successfully authenticated. | | `GetClientDeviceAuthToken.Failure` | The number of times the client device is not able to be authenticated. | | `SubscribeToCertificateUpdates.Success` | The number of successful subscriptions to certificate updates. | | `SubscribeToCertificateUpdates.Failure` | The number of unsuccessful attempts to subscribe to certificate updates. | | `ServiceError` | The number of unhandled internal errors across the client device auth. | | **Stream manager** – This feature requires v2.7.0 or later of the Greengrass nucleus component. | | `BytesAppended` | The number of bytes of data appended to stream manager. | | `BytesUploadedToIoTAnalytics` | The number of bytes of data that stream manager exports to channels in AWS IoT Analytics. | | `BytesUploadedToKinesis` | The number of bytes of data that stream manager exports to streams in Amazon Kinesis Data Streams. | | `BytesUploadedToIoTSiteWise` | The number of bytes of data that stream manager exports to asset properties in AWS IoT SiteWise. | | `BytesUploadedToS3` | The number of bytes of data that stream manager exports to objects in Amazon S3. | | **System Metrics** – This feature requires v2.15.0 or later of the Greengrass nucleus component. | | `CPUArchitecture` | Device central processing unit architecture. | | `Family` | Device operating system family (Windows only). | | `KernelVersion` | Device kernel version (Unix only). | | `KnowledgeBaseArticles` | Knowledge Base articles installed on a device (Windows only). | | `OSBuildMajor` | Major build number of the operating system version (Windows only). | | `OSBuildMinor` | Minor build number of the operating system version (Windows only). | | `OSName` | Name of the device operating system. | | `OSVersion` | Marketing version of the device operating system. | ## Configure telemetry agent settings The telemetry agent uses the following default settings: + The telemetry agent aggregates telemetry data every hour. + The telemetry agent publishes a telemetry message every 24 hours. The telemetry agent publishes data using the MQTT protocol with a quality of service (QoS) level of 0, which means that it doesn't confirm delivery or retry publishing attempts. Telemetry messages share an MQTT connection with other messages for subscriptions destined for AWS IoT Core. Aside from your data link costs, the data transfer from the core to AWS IoT Core is without charge. This is because the agent publishes to an AWS reserved topic. However, depending on your use case, you might incur costs when you receive or process the data. You can enable or disable the telemetry agent feature for each Greengrass core device. You can also configure the intervals over which the core device aggregates and publishes data. To configure telemetry, customize the [telemetry configuration parameter](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-telemetry) when you deploy the [Greengrass nucleus component](greengrass-nucleus-component.md). ## Subscribe to telemetry data in EventBridge You can create rules in Amazon EventBridge that define how to process telemetry data published from the telemetry agent on the Greengrass core device. When EventBridge receives the data, it invokes the target actions defined in your rules. For example, you can create event rules that send notifications, store event information, take corrective action, or invoke other events. ### Telemetry events Telemetry events use the following format. ``` { "version": "0", "id": "a09d303e-2f6e-3d3c-a693-8e33f4fe3955", "detail-type": "Greengrass Telemetry Data", "source": "aws.greengrass", "account": "123456789012", "time": "2020-11-30T20:45:53Z", "region": "us-east-1", "resources": [], "detail": { "ThingName": "MyGreengrassCore", "Schema": "2020-07-30", "ADP": [ { "TS": 1602186483234, "NS": "SystemMetrics", "M": [ { "N": "TotalNumberOfFDs", "Sum": 6447.0, "U": "Count" }, { "N": "CpuUsage", "Sum": 15.458333333333332, "U": "Percent" }, { "N": "SystemMemUsage", "Sum": 10201.0, "U": "Megabytes" } ] }, { "TS": 1602186483234, "NS": "GreengrassComponents", "M": [ { "N": "NumberOfComponentsStopping", "Sum": 0.0, "U": "Count" }, { "N": "NumberOfComponentsStarting", "Sum": 0.0, "U": "Count" }, { "N": "NumberOfComponentsBroken", "Sum": 0.0, "U": "Count" }, { "N": "NumberOfComponentsFinished", "Sum": 1.0, "U": "Count" }, { "N": "NumberOfComponentsInstalled", "Sum": 0.0, "U": "Count" }, { "N": "NumberOfComponentsRunning", "Sum": 7.0, "U": "Count" }, { "N": "NumberOfComponentsNew", "Sum": 0.0, "U": "Count" }, { "N": "NumberOfComponentsErrored", "Sum": 0.0, "U": "Count" }, { "N": "NumberOfComponentsStateless", "Sum": 0.0, "U": "Count" } ] }, { "TS": 1602186483234, "NS": "aws.greengrass.ClientDeviceAuth", "M": [ { "N": "VerifyClientDeviceIdentity.Success", "Sum": 3.0, "U": "Count" }, { "N": "VerifyClientDeviceIdentity.Failure", "Sum": 1.0, "U": "Count" }, { "N": "AuthorizeClientDeviceActions.Success", "Sum": 20.0, "U": "Count" }, { "N": "AuthorizeClientDeviceActions.Failure", "Sum": 5.0, "U": "Count" }, { "N": "GetClientDeviceAuthToken.Success", "Sum": 5.0, "U": "Count" }, { "N": "GetClientDeviceAuthToken.Failure", "Sum": 2.0, "U": "Count" }, { "N": "SubscribeToCertificateUpdates.Success", "Sum": 10.0, "U": "Count" }, { "N": "SubscribeToCertificateUpdates.Failure", "Sum": 1.0, "U": "Count" }, { "N": "ServiceError", "Sum": 3.0, "U": "Count" } ] }, { "TS": 1602186483234, "NS": "aws.greengrass.StreamManager", "M": [ { "N": "BytesAppended", "Sum": 157745524.0, "U": "Bytes" }, { "N": "BytesUploadedToIoTAnalytics", "Sum": 149012.0, "U": "Bytes" }, { "N": "BytesUploadedToKinesis", "Sum": 12192.0, "U": "Bytes" }, { "N": "BytesUploadedToIoTSiteWise", "Sum": 13321.0, "U": "Bytes" }, { "N": "BytesUploadedToS3", "Sum": 12213.0, "U": "Bytes" } ] } { "TS": 1750104449426, "NS": "SystemMetrics", "M": [ { "N": "KernelVersion", "Sum": 1, "U": "6.1.140-154.222.amzn2023.x86_64" }, { "N": "OSVersion", "Sum": 1, "U": "2023.7.20250609" }, { "N": "OSName", "Sum": 1, "U": "Amazon Linux" }, { "N": "CPUArchitecture", "Sum": 1, "U": "Broadwell (Server)" }, ] } ] } } ``` The `ADP` array contains a list of aggregated data points that have the following properties: `TS` The timestamp of when the data was gathered. `NS` The metric namespace. `M` The list of metrics. A metric contains the following properties: `N` The name of the metric. `Sum` The sum of the metric's values in this telemetry event. `U` The unit of the metric value. For more information about each metric, see [Telemetry metrics](#telemetry-metrics). ### Prerequisites to create EventBridge rules Before you create an EventBridge rule for AWS IoT Greengrass, you should do the following: + Familiarize yourself with events, rules, and targets in EventBridge. + Create and configure the [targets](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-targets.html) invoked by your EventBridge rules. Rules can invoke many types of targets, such as Amazon Kinesis streams, AWS Lambda functions, Amazon SNS topics, and Amazon SQS queues. Your EventBridge rule, and the associated targets must be in the AWS Region where you created your Greengrass resources. For more information, see [Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) in the *AWS General Reference*. For more information, see [What is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html) and [Getting started with Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-getting-set-up.html) in the *Amazon EventBridge User Guide*. ### Create an event rule to get telemetry data (console) Use the following steps to use the AWS Management Console to create an EventBridge rule that receives telemetry data published by the Greengrass core device. This allows web servers, email addresses, and other topic subscribers to respond to the event. For more information, see [Creating a EventBridge rule that triggers on an event from an AWS resource](https://docs.aws.amazon.com/eventbridge/latest/userguide/create-eventbridge-rule.html) in the *Amazon EventBridge User Guide*. 1. Open the [Amazon EventBridge console](https://console.aws.amazon.com/events/), and choose **Create rule**. 1. Under **Name and description**, enter a name and description for the rule. 1. Under **Define pattern**, configure the rule pattern. 1. Choose **Event pattern**. 1. Choose **Pre-defined pattern by service**. 1. For **Service provider**, choose **AWS**. 1. For **Service name**, choose **Greengrass**. 1. For **Event type**, select **Greengrass Telemetry Data**. 1. Under **Select event bus**, keep the default event bus options. 1. Under **Select targets**, configure your target. The following example uses an Amazon SQS queue, but you can configure other target types. 1. For **Target**, choose **SQS queue**. 1. For **Queue\$1**, choose your target queue. 1. Under **Tags - optional**, define tags for the rule or leave the fields empty. 1. Choose **Create**. ### Create an event rule to get telemetry data (CLI) Use the following steps to use the AWS CLI to create an EventBridge rule that receives telemetry data published by Greengrass core devices. This allows web servers, email addresses, and other topic subscribers to respond to the event. 1. Create the rule. + Replace *thing-name* with the thing name of the core device. ------ #### [ Linux or Unix ] ``` aws events put-rule \ --name MyGreengrassTelemetryEventRule \ --event-pattern "{\"source\": [\"aws.greengrass\"], \"detail\": {\"ThingName\": [\"thing-name\"]}}" ``` ------ #### [ Windows Command Prompt (CMD) ] ``` aws events put-rule ^ --name MyGreengrassTelemetryEventRule ^ --event-pattern "{\"source\": [\"aws.greengrass\"], \"detail\": {\"ThingName\": [\"thing-name\"]}}" ``` ------ #### [ PowerShell ] ``` aws events put-rule ` --name MyGreengrassTelemetryEventRule ` --event-pattern "{\"source\": [\"aws.greengrass\"], \"detail\": {\"ThingName\": [\"thing-name\"]}}" ``` ------ Properties that are omitted from the pattern are ignored. 1. Add the topic as a rule target. The following example uses Amazon SQS but you can configure other target types. + Replace *queue-arn* with the ARN of your Amazon SQS queue. ------ #### [ Linux or Unix ] ``` aws events put-targets \ --rule MyGreengrassTelemetryEventRule \ --targets "Id"="1","Arn"="queue-arn" ``` ------ #### [ Windows Command Prompt (CMD) ] ``` aws events put-targets ^ --rule MyGreengrassTelemetryEventRule ^ --targets "Id"="1","Arn"="queue-arn" ``` ------ #### [ PowerShell ] ``` aws events put-targets ` --rule MyGreengrassTelemetryEventRule ` --targets "Id"="1","Arn"="queue-arn" ``` ------ **Note** To allow Amazon EventBridge to invoke your target queue, you must add a resource-based policy to your topic. For more information, see [Amazon SQS permissions](https://docs.aws.amazon.com/eventbridge/latest/userguide/resource-based-policies-eventbridge.html#sqs-permissions) in the *Amazon EventBridge User Guide*. For more information, see [Events and event patterns in EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html) in the *Amazon EventBridge User Guide*. # Get deployment and component health status notifications Amazon EventBridge event rules provide you with notifications about state changes for your Greengrass deployments received by your devices and for installed components on your device. EventBridge delivers a near real-time stream of system events that describes changes in AWS resources. AWS IoT Greengrass sends these events to EventBridge on a *best-effort* basis. This means that AWS IoT Greengrass attempts to send all events to EventBridge but, in some rare cases, an event might not be delivered. Additionally, AWS IoT Greengrass might send multiple copies of a given event, which means that your event listeners might not receive the events in the order that the events occurred. **Note** Amazon EventBridge is an event bus service that you can use to connect your applications with data from a variety of sources, such as [Greengrass core devices](telemetry.md) and deployment and component notifications. For more information, see [What is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html) in the *Amazon EventBridge User Guide*. **Topics** + [Deployment status change event](#deployment.events-message-format) + [Component status change event](#component.events-message-format) + [Prerequisites for creating EventBridge rules](#create-events-rule-prereqs) + [Configure device health notifications (console)](#create-events-rule-console) + [Configure device health notifications (CLI)](#create-events-rule-cli) + [Configure device health notifications (CloudFormation)](#create-events-rule-cloudformation) + [See also](#deployment-notifications-see-also) ## Deployment status change event AWS IoT Greengrass emits an event when a deployment enters the following states: `FAILED`, `SUCCEEDED`, `COMPLETED`, `REJECTED`, and `CANCELED`. You can create an EventBridge rule that runs for all state transitions or transitions to states you specify. When a deployment enters a state that initiates a rule, EventBridge invokes the target actions defined in the rule. This allows you to send notifications, capture event information, take corrective action, or initiate other events in response to a state change. For example, you can create rules for the following use cases: + Initiate post-deployment operations, such as downloading assets and notifying personnel. + Send notifications upon a successful or failed deployment. + Publish custom metrics about deployment events. The [event](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/CloudWatchEventsandEventPatterns.html) for a deployment state change uses the following format: ``` { "version":"0", "id":" cd4d811e-ab12-322b-8255-EXAMPLEb1bc8", "detail-type":"Greengrass V2 Effective Deployment Status Change", "source":"aws.greengrass", "account":"123456789012", "region":"us-west-2", "time":"2018-03-22T00:38:11Z", "resources":["arn:aws:greengrass:us-east-1:123456789012:coreDevices:MyGreengrassCore"], "detail":{ "deploymentId": "4f38f1a7-3dd0-42a1-af48-EXAMPLE09681", "coreDeviceExecutionStatus": "FAILED|SUCCEEDED|COMPLETED|REJECTED|CANCELED", "statusDetails": { "errorStack": ["DEPLOYMENT_FAILURE", "ARTIFACT_DOWNLOAD_ERROR", "S3_ERROR", "S3_ACCESS_DENIED", "S3_HEAD_OBJECT_ACCESS_DENIED"], "errorTypes": ["DEPENDENCY_ERROR", "PERMISSION_ERROR"], }, "reason": "S3_HEAD_OBJECT_ACCESS_DENIED: FAILED_NO_STATE_CHANGE: Failed to download artifact name: 's3://pentest27/nucleus/281/aws.greengrass.nucleus.zip' for component aws.greengrass.Nucleus-2.8.1, reason: S3 HeadObject returns 403 Access Denied. Ensure the IAM role associated with the core device has a policy granting s3:GetObject. null (Service: S3, Status Code: 403, Request ID: HR94ZNT2161DAR58, Extended Request ID: wTX4DDI+qigQt3uzwl9rlnQiYlBgwvPm/KJFWeFAn9t1mnGXTms/luLCYANgq08RIH+x2H+hEKc=)" } } ``` You can create rules and events that will update you on the status of a deployment. An event is initiated when a deployment completes as either `FAILED`, `SUCCEEDED`, `COMPLETED`, `REJECTED`, or `CANCELED`. If the deployment failed on the core device, you will receive a detailed response that explains why the deployment failed. For more information about deployment error codes, see [Detailed deployment error codes](troubleshooting-deployment.md). **Deployment states** + `FAILED`. The deployment failed. + `SUCCEEDED`. The deployment targeted to a thing group successfully completed. + `COMPLETED`. The deployment targeted to a thing successfully completed. + `REJECTED`. The deployment was rejected. For more information, see the `statusDetails` field. + `CANCELED`. The deployment was canceled by the user. It's possible that events might be duplicated or out of order. To determine the order of events, use the `time` property. For a full list of error codes in `errorStacks` and `errorTypes`, see [Detailed deployment error codes](troubleshooting-deployment.md) and [Detailed component status codes](troubleshooting-component.md). ## Component status change event For AWS IoT Greengrass versions 2.12.2 and earlier, Greengrass emits an event when a component enters the following states: `ERRORED` and `BROKEN`. For Greengrass nucleus versions 2.12.3 and later, Greengrass emits an event when a component enters the following states: `ERRORED`, `BROKEN`, `RUNNING`, and `FINISHED`. Greengrass will also emit an event when a deployment completes. You can create an EventBridge rule that runs for all state transitions or transitions to states you specify. When an installed component enters a state that initiates a rule, EventBridge invokes the target actions defined in the rule. This allows you to send notifications, capture event information, take corrective action, or initiate other events in response to a state change. The [event](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/CloudWatchEventsandEventPatterns.html) for a component state change uses the following formats: ------ #### [ Greengrass nucleus v2.12.2 and earlier ] Component status: `ERRORED` or `BROKEN` ``` { "version":"0", "id":" cd4d811e-ab12-322b-8255-EXAMPLEb1bc8", "detail-type":"Greengrass V2 Installed Component Status Change", "source":"aws.greengrass", "account":"123456789012", "region":"us-west-2", "time":"2018-03-22T00:38:11Z", "resources":["arn:aws:greengrass:us-east-1:123456789012:coreDevices:MyGreengrassCore"], "detail": { "components": [ { "componentName": "MyComponent", "componentVersion": "1.0.0", "root": true, "lifecycleState": "ERRORED|BROKEN", "lifecycleStatusCodes": ["STARTUP_ERROR"], "lifecycleStateDetails": "An error occurred during startup. The startup script exited with code 1." } ] } } ``` ------ #### [ Greengrass nucleus v2.12.3 and later ] Component status: `ERRORED` or `BROKEN` ``` { "version":"0", "id":" cd4d811e-ab12-322b-8255-EXAMPLEb1bc8", "detail-type":"Greengrass V2 Installed Component Status Change", "source":"aws.greengrass", "account":"123456789012", "region":"us-west-2", "time":"2018-03-22T00:38:11Z", "resources":["arn:aws:greengrass:us-east-1:123456789012:coreDevices:MyGreengrassCore"], "detail": { "components": [ { "componentName": "MyComponent", "componentVersion": "1.0.0", "root": true, "lifecycleState": "ERRORED|BROKEN", "lifecycleStatusCodes": ["STARTUP_ERROR"], "lifecycleStateDetails": "An error occurred during startup. The startup script exited with code 1." } ] } } ``` Component status: `RUNNING` or `FINISHED` ``` { "version":"0", "id":" cd4d811e-ab12-322b-8255-EXAMPLEb1bc8", "detail-type":"Greengrass V2 Installed Component Status Change", "source":"aws.greengrass", "account":"123456789012", "region":"us-west-2", "time":"2018-03-22T00:38:11Z", "resources":["arn:aws:greengrass:us-east-1:123456789012:coreDevices:MyGreengrassCore"], "detail": { "components": [ { "componentName": "MyComponent", "componentVersion": "1.0.0", "root": true, "lifecycleState": "RUNNING|FINISHED", "lifecycleStateDetails": null } ] } } ``` ------ You can create rules and events that will update you on the status of an installed component. An event is initiated when a component changes state on the device. You will receive a detailed response that explains why a component is errored or broken. You will also receive a status code that will indicate a reason for the failure. For more information about component status codes, see [Detailed component status codes](troubleshooting-component.md). ## Prerequisites for creating EventBridge rules Before you create an EventBridge rule for AWS IoT Greengrass, do the following: + Familiarize yourself with events, rules, and targets in EventBridge. + Create and configure the targets invoked by your EventBridge rules. Rules can invoke many types of targets, including: + Amazon Simple Notification Service (Amazon SNS) + AWS Lambda functions + Amazon Kinesis Video Streams + Amazon Simple Queue Service (Amazon SQS) queues For more information, see [What is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html) and [Getting started with Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-getting-set-up.html) in the *Amazon EventBridge User Guide*. ## Configure device health notifications (console) Use the following steps to create an EventBridge rule that publishes an Amazon SNS topic when the deployment state changes for a group. This allows web servers, email addresses, and other topic subscribers to respond to the event. For more information, see [Creating a EventBridge rule that triggers on an event from an AWS resource](https://docs.aws.amazon.com/eventbridge/latest/userguide/create-eventbridge-rule.html) in the *Amazon EventBridge User Guide*. 1. Open the [Amazon EventBridge console](https://console.aws.amazon.com/events/). 1. In the navigation pane, choose **Rules**. 1. Choose **Create rule**. 1. Enter a name and description for the rule. A rule can't have the same name as another rule in the same Region and on the same event bus. 1. For **Event bus**, choose the event bus that you want to associate with this rule. If you want this rule to match events that come from your account, select **AWS default event bus**. When an AWS service in your account emits an event, it always goes to your account's default event bus. 1. For **Rule type**, choose **Rule with an event pattern**. 1. Choose **Next**. 1. For **Event source**, choose **AWS events**. 1. For **Event pattern**, choose **AWS services**. 1. For **AWS service**, choose Greengrass. 1. For **Event type**, choose from the following: + For deployment events, choose **Greengrass V2 Effective Deployment Status Change**. + For component events, choose **Greengrass V2 Installed Component Status Change**. 1. Choose **Next**. 1. For **Target types**, choose **AWS service**. 1. For **Select a target**, configure your target. This example uses an Amazon SNS topic, but you can configure other target types to send notifications. 1. For **Target**, choose **SNS topic**. 1. For **Topic**, choose your target topic. 1. Choose **Next**. 1. Choose **Next**. 1. Review the details of the rule and choose **Create rule**. ## Configure device health notifications (CLI) Use the following steps to create an EventBridge rule that publishes an Amazon SNS topic when there is a Greengrass status change event. This allows web servers, email addresses, and other topic subscribers to respond to the event. 1. Create the rule. + For deployment status change events. ``` aws events put-rule \ --name TestRule \ --event-pattern "{\"source\": [\"aws.greengrass\"], \"detail-type\": [\"Greengrass V2 Effective Deployment Status Change\"]}" ``` + For component status change events. ``` aws events put-rule \ --name TestRule \ --event-pattern "{\"source\": [\"aws.greengrass\"], \"detail-type\": [\"Greengrass V2 Installed Component Status Change\"]}" ``` Properties that are omitted from the pattern are ignored. 1. Add the topic as a rule target. + Replace *topic-arn* with the ARN of your Amazon SNS topic. ``` aws events put-targets \ --rule TestRule \ --targets "Id"="1","Arn"="topic-arn" ``` **Note** To allow Amazon EventBridge to call your target topic, you must add a resource-based policy to your topic. For more information, see [Amazon SNS permissions](https://docs.aws.amazon.com/eventbridge/latest/userguide/resource-based-policies-eventbridge.html#sns-permissions) in the *Amazon EventBridge User Guide*. For more information, see [Events and event patterns in EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html) in the *Amazon EventBridge User Guide*. ## Configure device health notifications (CloudFormation) Use CloudFormation templates to create EventBridge rules that send notifications about state changes for your Greengrass group deployments. For more information, see [Amazon EventBridge resource type reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/AWS_Events.html) in the *AWS CloudFormation User Guide*. ## See also + [Check device deployment status](check-deployment-status.md#check-device-deployment-status) + [What is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/what-is-amazon-eventbridge.html) in the *Amazon EventBridge User Guide* # Check Greengrass core device status Greengrass core devices report the status of their software components to AWS IoT Greengrass. You can check the health summary of each device, and you can check the status of each component on each device. Core devices have the following health statuses: + `HEALTHY` – The AWS IoT Greengrass Core software and all components run without issue on the core device. + `UNHEALTHY` – The AWS IoT Greengrass Core software or a component is in an error state on the core device. **Note** AWS IoT Greengrass relies on individual devices to send status updates to the AWS Cloud. If the AWS IoT Greengrass Core software isn't running on the device, or if device isn't connected to the AWS Cloud, then the reported status of that device might not reflect its current status. The status timestamp indicates when the device status was last updated. Core devices send status updates at the following times: When the AWS IoT Greengrass Core software starts When the core device receives a deployment from the AWS Cloud For Greengrass nucleus 2.12.2 and earlier, the core device sends status updates when the status of any component on the core device becomes `ERRORED` or `BROKEN` For Greengrass nucleus 2.12.3 and later, the core device sends status updates when the status of any component on the core device becomes `ERRORED`, `BROKEN`, `RUNNING`, or `FINISHED` At a [regular interval that you can configure](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-fss), which defaults to 24 hours For AWS IoT Greengrass Core v2.7.0 and later, the core device sends status updates when local deployment and cloud deployment occurs **Topics** + [Check health of a core device](#check-core-device-health-status) + [Check health of a core device group](#check-core-device-group-health-status) + [Check core device component status](#check-core-device-component-status) ## Check health of a core device You can check the status of individual core devices. **To check the status of a core device (AWS CLI)** + Run the following command to retrieve the status of a device. Replace *coreDeviceName* with the name of the core device to query. ``` aws greengrassv2 get-core-device --core-device-thing-name coreDeviceName ``` The response contains information about the core device, including its status. ## Check health of a core device group You can check the status of a group of core devices (a thing group). **To check the status of a group of devices (AWS CLI)** + Run the following command to retrieve the status of multiple core devices. Replace the ARN in the command with the ARN of the thing group to query. ``` aws greengrassv2 list-core-devices --thing-group-arn "arn:aws:iot:region:account-id:thinggroup/thingGroupName" ``` The response contains the list of core devices in the thing group. Each entry in the list contains the status of the core device. ## Check core device component status You can check the status, such as lifecycle state, of the software components on a core device. For more information about component lifecycle states, see [Develop AWS IoT Greengrass components](develop-greengrass-components.md). **To check the status of components on a core device (AWS CLI)** + Run the following command to retrieve the status of the components on a core device. Replace *coreDeviceName* with the name of the core device to query. ``` aws greengrassv2 list-installed-components --core-device-thing-name coreDeviceName ``` The response contains the list of components that run on the core device. Each entry in the list contains the lifecycle state of the component, including how current the status of the data is and when the Greengrass core device last sent a message containing a certain component to the cloud. The response will also include the most recent deployment source that brought the component to the Greengrass core device. **Note** This command retrieves a paginated list of the components that a Greengrass core device runs. By default, this list doesn't include components that are deployed as dependencies of other components. You can include dependencies in the response by setting the `topologyFilter` parameter to `ALL`.