# Monitoring AWS IoT
Monitoring is an important part of maintaining the reliability, availability, and performance of AWS IoT and your AWS solutions.
We strongly encourage you to collect monitoring data from all parts of your AWS solution to make it easier to debug a multi-point failure, if one occurs. Start by creating a monitoring plan that answers the following questions. If you're not sure how to answer these, you can still continue to [enable logging](configure-logging.md) and establish your performance baselines.
+ 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?
Your next step is to [enable logging](configure-logging.md) and establish a baseline of normal AWS IoT performance in your environment by measuring performance at various times and under different load conditions. As you monitor AWS IoT, keep historical monitoring data so that you can compare it with current performance data. This will help you identify normal performance patterns and performance anomalies, and devise methods to address issues.
To establish your baseline performance for AWS IoT, you should monitor these metrics to start. You can always monitor more metrics later.
+ [`PublishIn.Success`](metrics_dimensions.md#message-broker-metrics)
+ [`PublishOut.Success`](metrics_dimensions.md#message-broker-metrics)
+ [`Subscribe.Success`](metrics_dimensions.md#message-broker-metrics)
+ [`Ping.Success`](metrics_dimensions.md#message-broker-metrics)
+ [`Connect.Success`](metrics_dimensions.md#message-broker-metrics)
+ [`GetThingShadow.Accepted`](metrics_dimensions.md#shadow-metrics)
+ [`UpdateThingShadow.Accepted`](metrics_dimensions.md#shadow-metrics)
+ [`DeleteThingShadow.Accepted`](metrics_dimensions.md#shadow-metrics)
+ [`RulesExecuted`](metrics_dimensions.md#iot-metrics)
The topics in this section can help you start logging and monitoring AWS IoT.
**Topics**
+ [Configure AWS IoT logging](configure-logging.md)
+ [Monitor AWS IoT alarms and metrics using Amazon CloudWatch](monitoring-cloudwatch.md)
+ [Monitor AWS IoT using CloudWatch Logs](cloud-watch-logs.md)
+ [Upload device-side logs to Amazon CloudWatch](upload-device-logs-to-cloudwatch.md)
+ [Logging AWS IoT API calls using AWS CloudTrail](iot-using-cloudtrail.md)
# Configure AWS IoT logging
You must enable logging by using the AWS IoT console, CLI, or API before you can monitor and log AWS IoT activity. You can configure logging for AWS IoT at three levels: account-level, event-level or resource-specific level. Event-level and resource-specific logging are available exclusively with V2 logging. Customers using V1 logging must perform a migration to V2 to access these features. See [details](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#migration-v1-v2).
When considering how to configure your AWS IoT logging, the account-level logging configuration determines how AWS IoT activity will be logged unless specified otherwise. Starting out, you might want to obtain detailed logs with a default [log level](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#log-level) of INFO or DEBUG. After reviewing the initial logs, you can change the default log level to a less verbose level such as WARN or ERROR at account or event level and set a more verbose resource-specific log level on resources that might need more attention. Log levels can be changed whenever you want.
This topic covers cloud-side logging in AWS IoT. For information on device-side logging and monitoring, see [Upload device-side logs to CloudWatch](https://docs.aws.amazon.com/iot/latest/developerguide/upload-device-logs-to-cloudwatch.html).
For information on logging and monitoring AWS IoT Greengrass, see [Logging and monitoring in AWS IoT Greengrass](https://docs.aws.amazon.com/greengrass/v2/developerguide/logging-and-monitoring.html).
## Configuring V2 logging in AWS IoT
### Determing your logging version
The [GetV2LoggingOptions API](https://docs.aws.amazon.com/iot/latest/apireference/API_GetV2LoggingOptions.html) returns a NotConfiguredException if V2 logging is not enabled. This error occurs when either V1 logging is in use, or no logging has been configured.
### Understanding V2 logging features
V2 logging provides two key capabilities: event-level logging and resource-specific logging. Event-level logging enables targeted logging configuration with customizable log levels and CloudWatch log group destinations. Resource-specific logging allows you to filter logs by thing group, source IP, client ID, or principal ID. Together, these features provide granular control and comprehensive visibility into IoT operations, improving log searchability and reducing costs by eliminating unnecessary logging activity.
### Migrating from V1 to V2
You can migrate to V2 logging using the SetV2LoggingOptions API through either the AWS [CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/set-v2-logging-options.html) or SDK. After migration, AWS IoT automatically routes all logs to the CloudWatch log group 'AWSIotLogsV2'. Important: If your downstream applications or resources consume information from ‘AWSIotLogs’, update them to use the corresponding log group path.
## Configure logging role and policy
Before you can enable logging in AWS IoT, you must create an IAM role and a policy that gives AWS IoT permission to write AWS IoT log activities to CloudWatch log groups on your behalf. You can also generate an IAM role with the policies needed in the [Logs section of the AWS IoT console](https://console.aws.amazon.com/iot/home#/settings/logging).
**Note**
Before enabling AWS IoT logging, ensure you understand the CloudWatch Logs access permissions. Users with access to CloudWatch Logs can see debugging information from your devices. For more information, see [Authentication and Access Control for Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/auth-and-access-control-cw.html).
If you expect high traffic patterns in AWS IoT Core due to load testing, consider disabling IoT logging to prevent throttling. If high traffic is detected, our service may disable logging in your account.
The following shows how to create a logging role and policy for AWS IoT Core resources.
### Create a logging role
To create a logging role, open the [Roles hub of the IAM console](https://console.aws.amazon.com/iam/home#/roles) and choose **Create role**.
1. Under **Select trusted entity**, choose **AWS Service**. Then choose **IoT** under **Use case**. If you don't see **IoT**, enter and search **IoT** from the **Use cases for other AWS services:** drop-down menu. Select **Next**.
1. On the **Add permissions** page, you will see the policies that are automatically attached to the service role. Choose **Next**.
1. On the **Name, review, and create** page, enter a **Role name** and **Role description** for the role, then choose **Create role**.
### Logging role policy
The following policy documents provide the role policy and trust policy that allow AWS IoT to submit log entries to CloudWatch on your behalf. If you configure event-level logging with a custom CloudWatch log group, you must update the role policy to include the custom resource ARN.
If you also allowed AWS IoT Core for LoRaWAN to submit log entries, you'll see a policy document created for you that logs both activities.
**Note**
These documents were created for you when you created the logging role. The documents have variables, * `${partition}`, * * `${region}` *, and * `${accountId}` *, that you must replace with your values.
Replace partition with the partition of the region.
Replace region with the AWS Region that you use. Make sure that you use the same AWS Region that you used to configure the AWS CLI on your device.
Replace account-id with your AWS account ID.
Role policy:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:PutMetricFilter",
"logs:PutRetentionPolicy",
"iot:GetLoggingOptions",
"iot:SetLoggingOptions",
"iot:SetV2LoggingOptions",
"iot:GetV2LoggingOptions",
"iot:SetV2LoggingLevel",
"iot:ListV2LoggingLevels",
"iot:DeleteV2LoggingLevel"
],
"Resource": [
"arn:aws:logs:us-east-1:123456789012:log-group:AWSIotLogsV2:*"
]
}
]
}
```
Trust policy to log only AWS IoT Core activity:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
AWS IoT Logging may fail to publish logging to CloudWatch Logs due to insufficient IAM role permissions. When this occurs, check [ CloudWatch logging metrics](https://docs.aws.amazon.com/iot/latest/developerguide/metrics_dimensions.html#logging-metrics) to investigate and troubleshoot the failures.
## Configure logging in the AWS IoT (console)
This section describes how to configure AWS IoT logging using the AWS IoT console. You can set-up account-level, event-level and resource-specific logging.
**To configure AWS IoT logging:**
1. Sign in to the AWS IoT console. For more information, see [Open the AWS IoT console](setting-up.md#iot-console-signin).
1. In the left navigation pane, choose **Logs** (previously a section under Settings).
1. Configure account-level logging: account level logging applies to all your AWS IoT fleet (devices or endpoints), unless overridden by event-level or resource-specific settings.
1. Under Account-level logging, select **Manage account-level logging** to make updates.
1. Select the "Enable logging" checkbox to start sending logs to CloudWatch. When “Enable logging” is unchecked, AWS IoT will not send any logs to CloudWatch log groups, regardless of event-level or resource-level logging configurations.
1. Under **IAM log role**, select an existing role from the dropdown list. You can **View role details** to inspect role permissions. Alternatively, select **Create new role** to set up a new IAM role. The logging role provides policies that allow AWS IoT to submit log entries to CloudWatch on your behalf. If you configure event-level logging with a custom CloudWatch log group, you must update the role policy to include the ARN for this log group.
1. Choose the **Default Log level** that corresponds to the [level of detail](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#log-level) of the log entries that you want to appear in the CloudWatch Logs. Note: Log level “DEBUG” provides the most detail but increases CloudWatch costs. CloudWatch log group destinations cannot be configured at the account level. However, you can specify custom log groups for individual event types as described in the following section.
1. Choose **Update logging** to save your changes.
1. Event-level logging allows you to selectively capture logs for relevant events and direct them to dedicated CloudWatch log groups. This gives you the flexibility to organize logs by use cases for better discoverability, share them with different audiences, and reduce CloudWatch costs by enabling logs and setting log levels based on event criticality.
Configure **event-level logging**: event-level logging captures specific AWS IoT events, such as client authentication attempts. These settings override Account-Level Logging.
1. Under **Event-level logging** section, select **Manage event-level logging** to make updates.
1. By default, event types inherit the account-level logging configuration. Note: When resource-specific logging is configured, it overrides account and event-level settings.
1. To modify settings for individual events, click the value in the corresponding event row. You can adjust both the log level and the CloudWatch log group destination. When specifying a custom CloudWatch log group destination, you must verify that the IAM role policy includes permissions for the new log group. Failure to update the role policy will prevent AWS IoT from writing logs to the custom log group. After making your selection, click the check mark to confirm your choice. The **'Is Modified'** column will display 'Yes' to indicate pending changes.
1. Click on **Update Logging** to apply your changes or choose **Cancel** to discard.
1. Configure Resource-specific overrides: Resource-specific overrides apply a logging setting to selected resources. A resource can be a thing group, source IP, client ID, or principal ID. Resource-specific logging configuration overrides both account-level and event-level settings. When enabled, it generates logs for all event types at the configured logging level for the specified resources. For example, you can set debug-level logging for a specific Thing while keeping info-level logging for all other Things.
1. Select **Add resource-specific overrides** in the Resource-specific overrides section.
1. Choose a log target: Thing group, Source IP, Client ID or Principal ID.
1. Enter the corresponding log target value for your selected target type.
1. Select the desired log level from the dropdown menu in the Resource-specific log level section.
1. Click **Submit** to add the override or **Cancel** to discard changes.
1. To modify an existing resource-specific override, select the checkbox next to the resource and click “Remove” to delete the override or “Edit” to modify.
After you've enabled logging, visit [Viewing AWS IoT logs in the CloudWatch console](cloud-watch-logs.md#viewing-logs) to learn more about viewing the log entries.
## Configure Account and Event-level logging in AWS IoT (CLI)
This section describes how to configure global logging for AWS IoT by using the CLI.
You can optionally configure Event-level logging. Event-level logging captures logging information at the event level, such as authentication and authorization or certificate creation events. You can customize both the log level and the CloudWatch log group destinations at the event level. Event-level logging operates at a more targeted level compared with account-level logging and therefore overrides the account-level logging settings. This hierarchical approach allows you to maintain different logging strategies for different types of events based on their operational importance and cost considerations.
**Note**
You need the Amazon Resource Name (ARN) of the role that you want to use. If you need to create a role to use for logging, see [Create a logging role](#create-logging-role) before continuing. When specifying a custom CloudWatch log group for any event type, ensure your logging role has the required permissions for the target log group.
The principal used to call the API must have [Passing role permissions](pass-role.md) for your logging role.
You can also perform this procedure with the API by using the methods in the AWS API that correspond to the CLI commands shown here.
**To use the CLI to configure default logging for AWS IoT**
1. Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/set-v2-logging-options.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/set-v2-logging-options.html) command to set the logging options for your account.
```
aws iot set-v2-logging-options \
--event-configurations event-configuration-list \
--role-arn logging-role-arn \
--default-log-level log-level
```
where:
**--role-arn**
The role ARN that grants AWS IoT permission to write to your logs in CloudWatch Logs. Role-arn configuration is required for initial setup.
**--default-log-level**
The [log level](#log-level) to use. Valid values are: `ERROR`, `WARN`, `INFO`, `DEBUG`, or `DISABLED`. Default-log-level configuration is required for initial setup.
**--no-disable-all-logs**
An optional parameter that enables all AWS IoT logging. Use this parameter to enable logging when it is currently disabled.
**--disable-all-logs**
An optional parameter that disables all AWS IoT logging. Use this parameter to disable logging when it is currently enabled.
**--event-configurations**
This parameter is optional and allows you to customize logging settings for individual event types:
+ eventType: The type of event that overrides the account-level setting
+ logLevel: Override the account-level setting with DEBUG, INFO, ERROR, WARN, or DISABLED
+ logDestination: Specify a custom CloudWatch log group for log delivery
You can configure logging level and log destination independently for each event type. If not specified, events will inherit the account-level settings
```
aws iot set-v2-logging-options \
--event-configurations "[{\"eventType\":\"Publish-In\",\"logLevel\":\"INFO\",\"logDestination\":\"examplePublishInLogGroup\"}]"
```
1. Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/get-v2-logging-options.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/get-v2-logging-options.html) command to get your current logging options.
```
aws iot get-v2-logging-options \
--verbose
```
where:
**--verbose**
An optional parameter that enables you to retrieve all eventTypes and their configurations.
After you've enabled logging, visit [Viewing AWS IoT logs in the CloudWatch console](cloud-watch-logs.md#viewing-logs) to learn more about viewing the log entries.
**Note**
AWS IoT continues to support older commands (**set-logging-options** and **get-logging-options**) to set and get global logging on your account. Be aware that when these commands are used, the resulting logs contain plain-text, rather than JSON payloads and logging latency is generally higher. No further improvements will be made to the implementation of these older commands. We recommend that you use the ["v2" versions](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#migration-v1-v2) to configure your logging options and, when possible, change legacy applications that use the older versions.
## Configure Resource-specific overrides in AWS IoT (CLI)
This section describes how to configure Resource-specific overrides for AWS IoT by using the CLI. Resource-specific overrides allows you to specify a logging level for a specific resource identified by Thing Group, Client ID, Source IP, or Principal ID. When resource-specific logging is enabled, it overrides both account-level and event-level settings. All event types will generate logs for the specified resource at the configured logging level, even if those events are disabled in the event-level configurations.
Thing groups can contain other thing groups to create a hierarchical relationship. This procedure describes how to configure the logging of a single thing group. You can apply this procedure to the parent thing group in a hierarchy to configure the logging for all thing groups in the hierarchy. You can also apply this procedure to a child thing group to override the logging configuration of its parent.
A thing can be a member of a thing group. This membership allows the thing to inherit configurations, policies, and settings applied to the thing group. Thing groups are used to manage and apply settings to multiple things collectively, rather than dealing with each thing individually. When your client ID matches the thing name, AWS IoT Core will automatically associate the client session with the corresponding thing resource. This allows the client session to inherit the configurations and settings applied to the thing groups to which the thing belongs, including the logging levels. If your client ID doesn't match the thing name, you can enable the exclusive thing attachment to establish the association. For more information, see [Associating an AWS IoT thing to an MQTT client connection](exclusive-thing.md) .
In addition to thing groups, you can also log targets such as a device's client ID, source IP, and principal ID.
**Note**
You need the Amazon Resource Name (ARN) of the role you want to use. If you need to create a role to use for logging, see [Create a logging role](#create-logging-role) before continuing.
The principal used to call the API must have [Passing role permissions](pass-role.md) for your logging role.
You can also perform this procedure with the API by using the methods in the AWS API that correspond to the CLI commands shown here.
**To use the CLI to configure Resource-specific overrides for AWS IoT**
1. Enable account-level logging before configuring resource-specific logging using the following command: aws iot set-v2-logging-options command
1. Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/set-v2-logging-level.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/set-v2-logging-level.html) command to configure Resource-specific overrides. See the following example for thing group configuration:
```
aws iot set-v2-logging-level \
--log-target targetType=THING_GROUP,targetName=thing_group_name \
--log-level log_level
```
**--log-target**
The type and name of the resource for which you are configuring logging. The `targetType` value must be one of: `THING_GROUP` \$1 `CLIENT_ID` \$1 `SOURCE_IP` \$1 `PRINCIPAL_ID`. The log-target parameter value can be text, as shown in the preceding command example, or a JSON string, such as the following example.
```
aws iot set-v2-logging-level \
--log-target '{"targetType": "THING_GROUP","targetName": "thing_group_name"}' \
--log-level log_level
```
**--log-level**
The logging level used when generating logs for the specified resource. Valid values are: **DEBUG**, **INFO**, **ERROR**, **WARN**, and **DISABLED**.
1. Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-v2-logging-levels.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/list-v2-logging-levels.html) command to list the currently configured logging levels.
```
aws iot list-v2-logging-levels
```
1. Use the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/delete-v2-logging-level.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/delete-v2-logging-level.html) command to delete a resource-specific logging level, such as the following examples.
```
aws iot delete-v2-logging-level \
--target-type "THING_GROUP" \
--target-name "thing_group_name"
```
```
aws iot delete-v2-logging-level \
--target-type=CLIENT_ID
--target-name=ClientId1
```
**--target-type**
The `target-type` value must be one of: `THING_GROUP` \$1 `CLIENT_ID` \$1 `SOURCE_IP` \$1 `PRINCIPAL_ID`.
**--target-name**
The name of the thing group for which to remove the logging level.
## Log levels
These log levels determine the events that are logged and apply to default and resource-specific log levels.
ERROR
Any error that causes an operation to fail.
Example: failed to authenticate device due to expired certificate.
Logs include ERROR information only.
WARN
Anything that can potentially cause inconsistencies in the system, but might not cause the operation to fail.
Example: approaching message rate limit.
Logs include ERROR and WARN information.
INFO
High-level information about the flow of things.
Example: a client has successfully subscribed to an MQTT topic.
Logs include INFO, ERROR, and WARN information.
DEBUG
Information that might be helpful when debugging a problem.
Example: IoT Rules Engine detected a message published to the rules topic “rule/test” and successfully started executing. The rule is configured with RepublishAction.
Logs include DEBUG, INFO, ERROR, and WARN information.
DISABLED
All logging is disabled.
# Monitor AWS IoT alarms and metrics using Amazon CloudWatch
You can monitor AWS IoT using CloudWatch, which collects and processes raw data from AWS IoT into readable, near real-time metrics. These statistics are recorded for a period of two weeks, so that you can access historical information and gain a better perspective on how your web application or service is performing. By default, AWS IoT metric data is sent automatically to CloudWatch in one minute intervals. For more information, see [What Are Amazon CloudWatch, Amazon CloudWatch Events, and Amazon CloudWatch Logs?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatch.html) in the *Amazon CloudWatch User Guide*.
## Using AWS IoT metrics
The metrics reported by AWS IoT provide information that you can analyze in different ways. The following use cases are based on a scenario where you have ten things that connect to the internet once a day. Each day:
+ Ten things connect to AWS IoT at roughly the same time.
+ Each thing subscribes to a topic filter, and then waits for an hour before disconnecting. During this period, things communicate with one another and learn more about the state of the world.
+ Each thing publishes some perception it has based on its newly found data using `UpdateThingShadow`.
+ Each thing disconnects from AWS IoT.
To help you get started, these topics explore some of the questions that you might have.
+ [How can I be notified if my things do not connect successfully each day?](creating_alarms.md#how_to_detect_connection_failures)
+ [How can I be notified if my things are not publishing data each day?](creating_alarms.md#how_to_detect_publish_failures)
+ [How can I be notified if my thing's shadow updates are being rejected each day?](creating_alarms.md#detect_rejected_updates)
+ [How can I create a CloudWatch alarm for Jobs?](creating_alarms.md#cw-jobs-alarms)
**Topics**
+ [Using AWS IoT metrics](#how_to_use_metrics)
+ [Creating CloudWatch alarms to monitor AWS IoT](creating_alarms.md)
+ [AWS IoT metrics and dimensions](metrics_dimensions.md)
# Creating CloudWatch alarms to monitor AWS IoT
You can create a CloudWatch alarm that sends an Amazon SNS message when the alarm changes state. An alarm watches a single metric over a time period you specify. When the value of the metric exceeds a given threshold over a number of time periods, one or more actions are performed. The action can be a notification sent to an Amazon SNS topic or Auto Scaling policy. Alarms trigger actions for sustained state changes only. CloudWatch alarms do not trigger actions simply because they are in a particular state; the state must have changed and been maintained for a specified number of periods.
**Topics**
+ [How can I be notified if my things do not connect successfully each day?](#how_to_detect_connection_failures)
+ [How can I be notified if my things are not publishing data each day?](#how_to_detect_publish_failures)
+ [How can I be notified if my thing's shadow updates are being rejected each day?](#detect_rejected_updates)
+ [How can I create a CloudWatch alarm for jobs?](#cw-jobs-alarms)
You can see all the metrics that CloudWatch alarms can monitor at [AWS IoT metrics and dimensions](metrics_dimensions.md) .
## How can I be notified if my things do not connect successfully each day?
1. Create an Amazon SNS topic named `things-not-connecting-successfully`, and record its Amazon Resource Name (ARN). This procedure will refer to your topic's ARN as ` sns-topic-arn `.
For more information on how to create an Amazon SNS notification, see [Getting Started with Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html).
1. Create the alarm.
```
aws cloudwatch put-metric-alarm \
--alarm-name ConnectSuccessAlarm \
--alarm-description "Alarm when my Things don't connect successfully" \
--namespace AWS/IoT \
--metric-name Connect.Success \
--dimensions Name=Protocol,Value=MQTT \
--statistic Sum \
--threshold 10 \
--comparison-operator LessThanThreshold \
--period 86400 \
--evaluation-periods 1 \
--alarm-actions sns-topic-arn
```
1. Test the alarm.
```
aws cloudwatch set-alarm-state --alarm-name ConnectSuccessAlarm --state-reason "initializing" --state-value OK
```
```
aws cloudwatch set-alarm-state --alarm-name ConnectSuccessAlarm --state-reason "initializing" --state-value ALARM
```
1. Verify that the alarm appears in your [CloudWatch console](https://console.aws.amazon.com/cloudwatch).
## How can I be notified if my things are not publishing data each day?
1. Create an Amazon SNS topic named `things-not-publishing-data`, and record its Amazon Resource Name (ARN). This procedure will refer to your topic's ARN as ` sns-topic-arn `.
For more information on how to create an Amazon SNS notification, see [Getting Started with Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html).
1. Create the alarm.
```
aws cloudwatch put-metric-alarm \
--alarm-name PublishInSuccessAlarm\
--alarm-description "Alarm when my Things don't publish their data \
--namespace AWS/IoT \
--metric-name PublishIn.Success \
--dimensions Name=Protocol,Value=MQTT \
--statistic Sum \
--threshold 10 \
--comparison-operator LessThanThreshold \
--period 86400 \
--evaluation-periods 1 \
--alarm-actions sns-topic-arn
```
1. Test the alarm.
```
aws cloudwatch set-alarm-state --alarm-name PublishInSuccessAlarm --state-reason "initializing" --state-value OK
```
```
aws cloudwatch set-alarm-state --alarm-name PublishInSuccessAlarm --state-reason "initializing" --state-value ALARM
```
1. Verify that the alarm appears in your [CloudWatch console](https://console.aws.amazon.com/cloudwatch).
## How can I be notified if my thing's shadow updates are being rejected each day?
1. Create an Amazon SNS topic named `things-shadow-updates-rejected`, and record its Amazon Resource Name (ARN). This procedure will refer to your topic's ARN as ` sns-topic-arn `.
For more information on how to create an Amazon SNS notification, see [Getting Started with Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html).
1. Create the alarm.
```
aws cloudwatch put-metric-alarm \
--alarm-name UpdateThingShadowSuccessAlarm \
--alarm-description "Alarm when my Things Shadow updates are getting rejected" \
--namespace AWS/IoT \
--metric-name UpdateThingShadow.Success \
--dimensions Name=Protocol,Value=MQTT \
--statistic Sum \
--threshold 10 \
--comparison-operator LessThanThreshold \
--period 86400 \
--unit Count \
--evaluation-periods 1 \
--alarm-actions sns-topic-arn
```
1. Test the alarm.
```
aws cloudwatch set-alarm-state --alarm-name UpdateThingShadowSuccessAlarm --state-reason "initializing" --state-value OK
```
```
aws cloudwatch set-alarm-state --alarm-name UpdateThingShadowSuccessAlarm --state-reason "initializing" --state-value ALARM
```
1. Verify that the alarm appears in your [CloudWatch console](https://console.aws.amazon.com/cloudwatch).
## How can I create a CloudWatch alarm for jobs?
The Jobs service provides CloudWatch metrics for you to monitor your jobs. You can create CloudWatch alarms to monitor any [Jobs metrics](metrics_dimensions.md#jobs-metrics) .
The following command creates a CloudWatch alarm to monitor the total number of failed job executions for Job *SampleOTAJob* and notifies you when more than 20 job executions have failed. The alarm monitors the Jobs metric `FailedJobExecutionTotalCount` by checking the reported value every 300 seconds. It is activated when a single reported value is greater than 20, meaning there were more than 20 failed job executions since the job started. When the alarm goes off, it sends a notification to the provided Amazon SNS topic.
```
aws cloudwatch put-metric-alarm \
--alarm-name TotalFailedJobExecution-SampleOTAJob \
--alarm-description "Alarm when total number of failed job execution exceeds the threshold for SampleOTAJob" \
--namespace AWS/IoT \
--metric-name FailedJobExecutionTotalCount \
--dimensions Name=JobId,Value=SampleOTAJob \
--statistic Sum \
--threshold 20 \
--comparison-operator GreaterThanThreshold \
--period 300 \
--unit Count \
--evaluation-periods 1 \
--alarm-actions arn:aws:sns:::SampleOTAJob-has-too-many-failed-job-ececutions
```
The following command creates a CloudWatch alarm to monitor the number of failed job executions for Job *SampleOTAJob* in a given period. It then notifies you when more than five job executions have failed during that period. The alarm monitors the Jobs metric `FailedJobExecutionCount` by checking the reported value every 3600 seconds. It is activated when a single reported value is greater than 5, meaning there were more than 5 failed job executions in the past hour. When the alarm goes off, it sends a notification to the provided Amazon SNS topic.
```
aws cloudwatch put-metric-alarm \
--alarm-name FailedJobExecution-SampleOTAJob \
--alarm-description "Alarm when number of failed job execution per hour exceeds the threshold for SampleOTAJob" \
--namespace AWS/IoT \
--metric-name FailedJobExecutionCount \
--dimensions Name=JobId,Value=SampleOTAJob \
--statistic Sum \
--threshold 5 \
--comparison-operator GreaterThanThreshold \
--period 3600 \
--unit Count \
--evaluation-periods 1 \
--alarm-actions arn:aws:sns:::SampleOTAJob-has-too-many-failed-job-ececutions-per-hour
```
# AWS IoT metrics and dimensions
When you interact with AWS IoT, the service sends metrics and dimensions to CloudWatch every minute. You can use AWS IoT, use the CloudWatch console or AWS CLI to view these metrics.
To view metrics using the CloudWatch console, open the [CloudWatch console](https://console.aws.amazon.com/cloudwatch). In the navigation pane, choose **Metrics** and then choose **All metrics**. In the **Browse** tab, search for AWS IoT to view the list of metrics. Metrics are grouped first by the service namespace, and then by the various dimension combinations within each namespace.
To view metrics using AWS CLI, run the following command.
```
1. aws cloudwatch list-metrics --namespace "AWS/IoT"
```
**Topics**
+ [AWS IoT metrics](#iot-metrics)
+ [AWS IoT Core credential provider metrics](#credential-provider-metrics)
+ [Authentication metrics](#authentication-metrics)
+ [Server certificate OCSP stapling metrics](#server-ocsp-metrics)
+ [Rule metrics](#rulemetrics)
+ [Rule action metrics](#rule-action-metrics)
+ [HTTP action specific metrics](#http-action-metrics)
+ [Message broker metrics](#message-broker-metrics)
+ [Device shadow metrics](#shadow-metrics)
+ [Logging metrics](#logging-metrics)
+ [Jobs metrics](#jobs-metrics)
+ [Device Defender audit metrics](#device-defender-audit-metrics)
+ [Device Defender detect metrics](#device-defender-detect-metrics)
+ [Device provisioning metrics](#provisioning-metrics)
+ [LoRaWAN metrics](#lorawan-metrics)
+ [Fleet indexing metrics](#fleet-indexing-metrics)
+ [Dimensions for metrics](#aws-iot-metricdimensions)
## AWS IoT metrics
| Metric | Description |
| --- | --- |
| `AddThingToDynamicThingGroupsFailed` | The number of failure events associated with adding a thing to a dynamic thing group. The `DynamicThingGroupName` dimension contains the name of the dynamic groups that failed to add things. |
| `NumLogBatchesFailedToPublishThrottled` | The singular batch of log events that has failed to publish due to throttling errors. |
| `NumLogEventsFailedToPublishThrottled` | The number of log events within the batch that have failed to publish due to throttling errors. |
## AWS IoT Core credential provider metrics
| Metric | Description |
| --- | --- |
| `CredentialExchangeSuccess` | The number of successful `AssumeRoleWithCertificate` requests to AWS IoT Core credentials provider. |
## Authentication metrics
**Note**
The authentication metrics are displayed in the CloudWatch console under **Protocol Metrics**.
| Metric | Description |
| --- | --- |
| `Connection.AuthNError` | The number of connection attempts which AWS IoT Core rejects due to authentication failures. This metric only considers connections that send a Server Name Indication (SNI) string matching an endpoint of your AWS account. This metric includes connection attempts from external sources such as internet scanning tools or probing activities. The Protocol dimension contains the protocol used to send the connection attempt. |
## Server certificate OCSP stapling metrics
| Metric | Description |
| --- | --- |
| RetrieveOCSPStapleData.Success | The OCSP response has been received and processed successfully. This response will be included during the TLS handshake for the configured domain. The DomainConfigurationName dimension contains the name of configured domain with enabled server certificate OCSP stapling. |
## Rule metrics
| Metric | Description |
| --- | --- |
| `ParseError` | The number of JSON parse errors that occurred in messages published on a topic on which a rule is listening. The `RuleName` dimension contains the name of the rule. |
| `RuleExecutionThrottled` | The number of messages throttled by the rules engine because of malicious behavior or because the number of messages exceeds the rules engine's throttle limit. The `RuleName` dimension contains the name of the rule to be triggered. |
| `RuleNotFound` | The rule to be triggered could not be found. The `RuleName` dimension contains the name of the rule. |
| `RulesExecuted` | The number of AWS IoT rules executed. |
| `TopicMatch` | The number of incoming messages published on a topic on which a rule is listening. The `RuleName` dimension contains the name of the rule. |
## Rule action metrics
| Metric | Description |
| --- | --- |
| `Failure` | The number of failed rule action invocations. The `RuleName` dimension contains the name of the rule that specifies the action. The `ActionType` dimension contains the type of action that was invoked. |
| `Success` | The number of successful rule action invocations. The `RuleName` dimension contains the name of the rule that specifies the action. The `ActionType` dimension contains the type of action that was invoked. |
| ErrorActionFailure | The number of failed error actions. The RuleName dimension contains the name of the rule that specifies the action. The ActionType dimension contains the type of action that was invoked. |
| ErrorActionSuccess | The number of successful error actions. The RuleName dimension contains the name of the rule that specifies the action. The ActionType dimension contains the type of action that was invoked. |
## HTTP action specific metrics
| Metric | Description |
| --- | --- |
| `HttpCode_Other` | Generated if the status code of the response from the downstream web service/application is not 2xx, 4xx or 5xx. |
| `HttpCode_4XX` | Generated if the status code of the response from the downstream web service/application is between 400 and 499. |
| `HttpCode_5XX` | Generated if the status code of the response from the downstream web service/application is between 500 and 599. |
| `HttpInvalidUrl` | Generated if an endpoint URL, after substitution templates are replaced, does not start with `https://`. |
| `HttpRequestTimeout` | Generated if the downstream web service/application does not return response within request timeout limit. For more information, see [Service Quotas](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#limits_iot). |
| `HttpUnknownHost` | Generated if the URL is valid, but the service does not exist or is unreachable. |
## Message broker metrics
**Note**
The message broker metrics are displayed in the CloudWatch console under **Protocol Metrics**.
| Metric | Description |
| --- | --- |
| `Connect.AuthError` | The number of connection requests that could not be authorized by the message broker. The `Protocol` dimension contains the protocol used to send the `CONNECT` message. |
| `Connect.ClientError` | The number of connection requests rejected because the MQTT message did not meet the requirements defined in [AWS IoT quotas](limits-iot.md) . The `Protocol` dimension contains the protocol used to send the `CONNECT` message. |
| `Connect.ClientIDThrottle` | The number of connection requests throttled because the client exceeded the allowed connect request rate for a specific client ID. The `Protocol` dimension contains the protocol used to send the `CONNECT` message. |
| `Connect.ServerError` | The number of connection requests that failed because an internal error occurred. The `Protocol` dimension contains the protocol used to send the `CONNECT` message. |
| `Connect.Success` | The number of successful connections to the message broker. The `Protocol` dimension contains the protocol used to send the `CONNECT` message. |
| `Connect.Throttle` | The number of connection requests that were throttled because the account exceeded the allowed connect request rate. The `Protocol` dimension contains the protocol used to send the `CONNECT` message. |
| `Ping.Success` | The number of ping messages received by the message broker. The `Protocol` dimension contains the protocol used to send the ping message. |
| `PublishIn.AuthError` | The number of publish requests the message broker was unable to authorize. The `Protocol` dimension contains the protocol used to publish the message. HTTP Publish doesn't support this metric. |
| `PublishIn.ClientError` | The number of publish requests rejected by the message broker because the message did not meet the requirements defined in [AWS IoT quotas](limits-iot.md) . The `Protocol` dimension contains the protocol used to publish the message. |
| `PublishIn.ServerError` | The number of publish requests the message broker failed to process because an internal error occurred. The `Protocol` dimension contains the protocol used to send the `PUBLISH` message. |
| `PublishIn.Success` | The number of publish requests successfully processed by the message broker. The `Protocol` dimension contains the protocol used to send the `PUBLISH` message. |
| `PublishIn.Throttle` | The number of publish request that were throttled because the client exceeded the allowed inbound message rate. The `Protocol` dimension contains the protocol used to send the `PUBLISH` message. HTTP Publish doesn't support this metric. |
| `PublishOut.AuthError` | The number of publish requests made by the message broker that could not be authorized by AWS IoT. The `Protocol` dimension contains the protocol used to send the `PUBLISH` message. |
| `PublishOut.ClientError` | The number of publish requests made by the message broker that were rejected because the message did not meet the requirements defined in [AWS IoT quotas](limits-iot.md) . The `Protocol` dimension contains the protocol used to send the `PUBLISH` message. |
| `PublishOut.Success` | The number of publish requests successfully made by the message broker. The `Protocol` dimension contains the protocol used to send the `PUBLISH` message. |
| PublishOut.Throttle | The number of publish requests that were throttled because the client exceeded the allowed outbound message rate. The `Protocol` dimension contains the protocol used to send the `PUBLISH` message. |
| `PublishRetained.AuthError` | The number of publish requests with the `RETAIN` flag set that the message broker was unable to authorize. The `Protocol` dimension contains the protocol used to send the `PUBLISH` message. |
| PublishRetained.ServerError | The number of retained publish requests the message broker failed to process because an internal error occurred. The `Protocol` dimension contains the protocol used to send the `PUBLISH` message. |
| `PublishRetained.Success` | The number of publish requests with the `RETAIN` flag set that were successfully processed by the message broker. The `Protocol` dimension contains the protocol used to send the `PUBLISH` message. |
| `PublishRetained.Throttle` | The number of publish requests with the `RETAIN` flag set that were throttled because the client exceeded the allowed inbound message rate. The `Protocol` dimension contains the protocol used to send the `PUBLISH` message. |
| `Queued.Success` | The number of stored messages that were successfully processed by the message broker for clients that were disconnected from their persistent session. Messages with a QoS of 1 are stored while a client with a persistent session is disconnected. |
| `Queued.Throttle` | The number of messages that couldn't be stored and were throttled while clients with persistent sessions were disconnected. This occurs when clients exceed the [Queued messages per second per account](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#genref_queued_messages_per_second_per_account) limit. Messages with a QoS of 1 are stored while a client with a persistent session is disconnected. |
| `Queued.ServerError` | The number of messages that haven't been stored for a persistent session because of an internal error. When clients with a persistent session are disconnected, messages with a Quality of Service (QoS) of 1 are stored. |
| `Subscribe.AuthError` | The number of subscription requests made by a client that could not be authorized. The `Protocol` dimension contains the protocol used to send the `SUBSCRIBE` message. |
| `Subscribe.ClientError` | The number of subscribe requests that were rejected because the `SUBSCRIBE` message did not meet the requirements defined in [AWS IoT quotas](limits-iot.md) . The `Protocol` dimension contains the protocol used to send the `SUBSCRIBE` message. |
| `Subscribe.ServerError` | The number of subscribe requests that were rejected because an internal error occurred. The `Protocol` dimension contains the protocol used to send the `SUBSCRIBE` message. |
| `Subscribe.Success` | The number of subscribe requests that were successfully processed by the message broker. The `Protocol` dimension contains the protocol used to send the `SUBSCRIBE` message. |
| `Subscribe.Throttle` | The number of subscribe requests that were throttled because the allowed subscribe request rate limits were exceeded for your AWS account. These limits include Subscriptions per second per account, Subscriptions per account, and Subscriptions per connection described in [AWS IoT Core message broker and protocol limits and quotas](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits). The `Protocol` dimension contains the protocol used to send the `SUBSCRIBE` message. |
| Throttle.Exceeded | This metric will display in CloudWatch when an MQTT client is throttled on packets [per second per connection level limits](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#message-broker-limits). This metric doesn't apply to HTTP connections. |
| `Unsubscribe.ClientError` | The number of unsubscribe requests that were rejected because the `UNSUBSCRIBE` message did not meet the requirements defined in [AWS IoT quotas](limits-iot.md) . The `Protocol` dimension contains the protocol used to send the `UNSUBSCRIBE` message. |
| `Unsubscribe.ServerError` | The number of unsubscribe requests that were rejected because an internal error occurred. The `Protocol` dimension contains the protocol used to send the `UNSUBSCRIBE` message. |
| `Unsubscribe.Success` | The number of unsubscribe requests that were successfully processed by the message broker. The `Protocol` dimension contains the protocol used to send the `UNSUBSCRIBE` message. |
| `Unsubscribe.Throttle` | The number of unsubscribe requests that were rejected because the client exceeded the allowed unsubscribe request rate. The `Protocol` dimension contains the protocol used to send the `UNSUBSCRIBE` message. |
## Device shadow metrics
**Note**
The device shadow metrics are displayed in the CloudWatch console under **Protocol Metrics**.
| Metric | Description |
| --- | --- |
| `DeleteThingShadow.Accepted` | The number of `DeleteThingShadow` requests processed successfully. The `Protocol` dimension contains the protocol used to make the request. |
| `GetThingShadow.Accepted` | The number of `GetThingShadow` requests processed successfully. The `Protocol` dimension contains the protocol used to make the request. |
| `ListThingShadow.Accepted` | The number of `ListThingShadow` requests processed successfully. The `Protocol` dimension contains the protocol used to make the request. |
| `UpdateThingShadow.Accepted` | The number of `UpdateThingShadow` requests processed successfully. The `Protocol` dimension contains the protocol used to make the request. |
## Logging metrics
| Metric | Description |
| --- | --- |
| `CloudwatchLogs:LogGroupCreationFailed` | The number of `CreateLogGroup` request failures. AWS IoT Logging creates CloudWatch log group if it doesn't exist. The `LogGroup` dimension contains the log group used to make the request. |
| `CloudwatchLogs:LogStreamCreationFailed` | The number of `CreateLogStream` request failures. AWS IoT Logging creates CloudWatch log stream to push log events. The `LogGroup` dimension contains the log group used to make the request. |
| `CloudwatchLogs:PutRetentionPolicyFailed` | The number of `PutRetentionPolicy` request failures. AWS IoT Logging creates CloudWatch log group if it doesn't exist, and the retention policy is set as 30 days. The `LogGroup` dimension contains the log group used to make the request. |
| `CloudwatchLogs:PutLogEventsFailed` | The number of `PutLogEvents` request failures. The `LogGroup` dimension contains the CloudWatch log group used to make the request. |
## Jobs metrics
| Metric | Description |
| --- | --- |
| `CanceledJobExecutionCount` | The number of job executions whose status has changed to `CANCELED` within a time period that is determined by CloudWatch. (For more information about CloudWatch metrics, see [Amazon CloudWatch Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Metric).) The `JobId` dimension contains the ID of the job. |
| `CanceledJobExecutionTotalCount` | The total number of job executions whose status is `CANCELED` for the given job. The `JobId` dimension contains the ID of the job. |
| `ClientErrorCount` | The number of client errors generated while executing the job. The `JobId` dimension contains the ID of the job. |
| `FailedJobExecutionCount` | The number of job executions whose status has changed to `FAILED` within a time period that is determined by CloudWatch. (For more information about CloudWatch metrics, see [Amazon CloudWatch Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Metric).) The `JobId` dimension contains the ID of the job. |
| `FailedJobExecutionTotalCount` | The total number of job executions whose status is `FAILED` for the given job. The `JobId` dimension contains the ID of the job. |
| `InProgressJobExecutionCount` | The number of job executions whose status has changed to `IN_PROGRESS` within a time period that is determined by CloudWatch. (For more information about CloudWatch metrics, see [Amazon CloudWatch Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Metric).) The `JobId` dimension contains the ID of the job. |
| `InProgressJobExecutionTotalCount` | The total number of job executions whose status is `IN_PROGRESS` for the given job. The `JobId` dimension contains the ID of the job. |
| `RejectedJobExecutionTotalCount` | The total number of job executions whose status is `REJECTED` for the given job. The `JobId` dimension contains the ID of the job. |
| `RemovedJobExecutionTotalCount` | The total number of job executions whose status is `REMOVED` for the given job. The `JobId` dimension contains the ID of the job. |
| `QueuedJobExecutionCount` | The number of job executions whose status has changed to `QUEUED` within a time period that is determined by CloudWatch. (For more information about CloudWatch metrics, see [Amazon CloudWatch Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Metric).) The `JobId` dimension contains the ID of the job. |
| `QueuedJobExecutionTotalCount` | The total number of job executions whose status is `QUEUED` for the given job. The `JobId` dimension contains the ID of the job. |
| `RejectedJobExecutionCount` | The number of job executions whose status has changed to `REJECTED` within a time period that is determined by CloudWatch. (For more information about CloudWatch metrics, see [Amazon CloudWatch Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Metric).) The `JobId` dimension contains the ID of the job. |
| `RemovedJobExecutionCount` | The number of job executions whose status has changed to `REMOVED` within a time period that is determined by CloudWatch. (For more information about CloudWatch metrics, see [Amazon CloudWatch Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Metric).) The `JobId` dimension contains the ID of the job. |
| `ServerErrorCount` | The number of server errors generated while executing the job. The `JobId` dimension contains the ID of the job. |
| `SuccededJobExecutionCount` | The number of job executions whose status has changed to `SUCCESS` within a time period that is determined by CloudWatch. (For more information about CloudWatch metrics, see [Amazon CloudWatch Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Metric).) The `JobId` dimension contains the ID of the job. |
| `SuccededJobExecutionTotalCount` | The total number of job executions whose status is `SUCCESS` for the given job. The `JobId` dimension contains the ID of the job. |
## Device Defender audit metrics
| Metric | Description |
| --- | --- |
| `NonCompliantResources` | The number of resources that were found to be noncompliant with a check. The system reports the number of resources that were out of compliance for each check of each audit performed. |
| `ResourcesEvaluated` | The number of resources that were evaluated for compliance. The system reports the number of resources that were evaluated for each check of each audit performed. |
| `MisconfiguredDeviceDefenderNotification` | Notifies you when your SNS configuration for AWS IoT Device Defender is misconfigured. [Dimensions](#aws-iot-metricdimensions) |
## Device Defender detect metrics
| Metric | Description |
| --- | --- |
| `NumOfMetricsExported` | The number of metrics exported for a cloud-side, device-side, or custom metric. The system reports the number of metrics exported for the account, for a specific metric. This metric is available only for customers using metrics export. |
| `NumOfMetricsSkipped` | The number of metrics skipped for a cloud-side, device-side, or custom metric. The system reports the number of metrics skipped for the account, for a specific metric due to insufficient permissions provided to Device Defender Detect to publish to the mqtt topic. This metric is available only for customers using metrics export. |
| `NumOfMetricsExceedingSizeLimit` | The number of metrics skipped for export for a cloud-side, device-side, or custom metric due to size exceeding MQTT message size constraints. The system reports the number of metrics skipped for export for the account, for a specific metric due to size exceeding MQTT message size constraints. This metric is available only for customers using metrics export. |
| `Violations` | The number of new violations of security profile behaviors that have been found since the last time an evaluation was performed. The system reports the number of new violations for the account, for a specific security profile, and for a specific behavior of a specific security profile. |
| `ViolationsCleared` | The number of violations of security profile behaviors that have been resolved since the last time an evaluation was performed. The system reports the number of resolved violations for the account, for a specific security profile, and for a specific behavior of a specific security profile. |
| `ViolationsInvalidated` | The number of violations of security profile behaviors for which information is no longer available since the last time an evaluation was performed (because the reporting device stopped reporting, or is no longer being monitored for some reason). The system reports the number of invalidated violations for the entire account, for a specific security profile, and for a specific behavior of a specific security profile. |
| `MisconfiguredDeviceDefenderNotification` | Notifies you when your SNS configuration for AWS IoT Device Defender is misconfigured. [Dimensions](#aws-iot-metricdimensions) |
## Device provisioning metrics
**AWS IoT Fleet provisioning metrics**
| Metric | Description |
| --- | --- |
| `ApproximateNumberOfThingsRegistered` | The count of things that have been registered by Fleet Provisioning. While the count is generally accurate, the distributed architecture of AWS IoT Core makes it difficult to maintain a precise count of registered things. The statistic to use for this metric is: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/metrics_dimensions.html) Dimensions: [ClaimCertificateId](#aws-iot-metricdimensions) |
| `CreateKeysAndCertificateFailed` | The number of failures that occurred by calls to the `CreateKeysAndCertificate` MQTT API. The metric is emitted in both Success (value = 0) and Failure (value = 1) cases. This metric can be used to track the number of certificates created and registered during the CloudWatch-supported aggregation windows, such as 5 min. or 1 hour. The statistics available for this metric are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/metrics_dimensions.html) |
| `CreateCertificateFromCsrFailed` | The number of failures that occurred by calls to the `CreateCertificateFromCsr` MQTT API. The metric is emitted in both Success (value = 0) and Failure (value = 1) cases. This metric can be used to track the number of things registered during the CloudWatch-supported aggregation windows, such as 5 min. or 1 hour. The statistics available for this metric are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/metrics_dimensions.html) |
| `RegisterThingFailed` | The number of failures that occurred by calls to the `RegisterThing` MQTT API. The metric is emitted in both Success (value = 0) and Failure (value = 1) cases. This metric can be used to track the number of things registered during the CloudWatch-supported aggregation windows, such as 5 min. or 1 hour. For the total number of things registered , see the `ApproximateNumberOfThingsRegistered` metric. The statistics available for this metric are: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/metrics_dimensions.html) Dimensions: [TemplateName](#aws-iot-metricdimensions) |
**Just-in-time provisioning metrics**
| Metric | Description |
| --- | --- |
| `ProvisionThing.ClientError` | The number of times a device failed to provision due to a client error. For example, the policy specified in the template did not exist. |
| ProvisionThing.ServerError | The number of times a device failed to provision due to a server error. Customers can retry to provision the device after waiting and they can contact AWS IoT if the issue remains the same. |
| ProvisionThing.Success | The number of times a device was successfully provisioned. |
## LoRaWAN metrics
The following table shows the metrics for AWS IoT Core for LoRaWAN. For more information, see [AWS IoT Core for LoRaWAN metrics](https://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-lorawan-metrics.html).
**AWS IoT Core for LoRaWAN metrics**
| Metric | Description |
| --- | --- |
| Active devices/gateways | The number of active LoRaWAN devices and gateways in your account. |
| Uplink message count | The number of uplink messages that are sent within a specified time duration for all active gateways and devices in your AWS account. Uplink messages are messages that are sent from your device to AWS IoT Core for LoRaWAN. |
| Downlink message count | The number of downlink messages that are sent within a specified time duration for all active gateways and devices in your AWS account. Downlink messages are messages that are sent from AWS IoT Core for LoRaWAN to your device. |
| Message loss rate | After you've added your device and connected to AWS IoT Core for LoRaWAN, your device can initiate an uplink message to start exchanging messages with the cloud. You can use this metric to then track the rate of uplink messages that are lost. |
| Join metrics | After you've added your device and gateway, you perform a join procedure so that your device can send uplink data and communicate with AWS IoT Core for LoRaWAN. You can use this metric to obtain information about join metrics for all active devices in your AWS account. |
| Average received signal strength indicator (RSSI) | You can use this metric to monitor the average RSSI (Received signal strength indicator) within the specified time duration. RSSI is a measurement that indicates if the signal is strong enough for a good wireless connection. This value is negative and must be closer to zero for a strong connection. |
| Average signal to noise ratio (SNR) | You can use this metric to monitor the average SNR (Signal-to-noise ratio) within the specified time duration. SNR is a measurement that indicates if the received signal is strong enough compared to the noise level for a good wireless connection. The SNR value is positive and must be greater than zero to indicate that the signal power is stronger than the noise power. |
| Gateway availability | You can use this metric to obtain information about the availability of this gateway within a specified time duration. This metric displays the websocket connection time of this gateway for a specified time duration. |
**Just-in-time provisioning metrics**
| Metric | Description |
| --- | --- |
| `ProvisionThing.ClientError` | The number of times a device failed to provision due to a client error. For example, the policy specified in the template did not exist. |
| ProvisionThing.ServerError | The number of times a device failed to provision due to a server error. Customers can retry to provision the device after waiting and they can contact AWS IoT if the issue remains the same. |
| ProvisionThing.Success | The number of times a device was successfully provisioned. |
## Fleet indexing metrics
**AWS IoT fleet indexing metrics**
| Metric | Description |
| --- | --- |
| `NamedShadowCountForDynamicGroupQueryLimitExceeded` | A maximum of 25 named shadows per thing are processed for query terms that are not data source specific in dynamic thing groups. When this limit is breached for a thing, the `NamedShadowCountForDynamicGroupQueryLimitExceeded` event type will be emitted. |
## Dimensions for metrics
**Metrics use the namespace and provide metrics for the following dimensions**
| Dimension | Description |
| --- | --- |
| ActionType | The [action type](iot-rule-actions.md) specified by the rule that triggered the request. |
| `BehaviorName` | The name of the Device Defender Detect security profile behavior that is being monitored. |
| `ClaimCertificateId` | The `certificateId` of the claim used to provision the devices. |
| `CheckName` | The name of the Device Defender audit check whose results are being monitored. |
| `JobId` | The ID of the job whose progress or message connection success/failure is being monitored. |
| `Protocol` | The protocol used to make the request. Valid values are: MQTT or HTTP |
| `RuleName` | The name of the rule triggered by the request. |
| `ScheduledAuditName` | The name of the Device Defender scheduled audit whose check results are being monitored. This has the value `OnDemand` if the results reported are for an audit that was performed on demand. |
| `SecurityProfileName` | The name of the Device Defender Detect security profile whose behaviors are being monitored. |
| `TemplateName` | The name of the provisioning template. |
| SourceArn | Refers to the security profile for detect or the account arn for audit. |
| `RoleArn` | Refers to the role Device Defender attempted to assume. |
| `TopicArn` | Refers to the SNS topic Device Defender attempted to publish to. |
| `Error` | Gives a short description of the Error received while attempting to publish to the SNS topic. Possible values are:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/metrics_dimensions.html) |
# Monitor AWS IoT using CloudWatch Logs
When [AWS IoT logging is enabled](configure-logging.md), AWS IoT sends progress events about each message as it passes from your devices through the message broker and rules engine. In the [CloudWatch console](https://console.aws.amazon.com/cloudwatch), CloudWatch logs appear in a log group named **AWSIotLogs**.
For more information about CloudWatch Logs, see [CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatchLogs.html). For information about supported AWS IoT CloudWatch Logs, see [CloudWatch Logs AWS IoT log entries](cwl-format.md) .
## Viewing AWS IoT logs in the CloudWatch console
**Note**
The `AWSIotLogsV2` log group is not visible in the CloudWatch console until:
You've enabled logging in AWS IoT. For more info on how to enable logging in AWS IoT, see [Configure AWS IoT logging](configure-logging.md)
Some log entries have been written by AWS IoT operations.
**To view your AWS IoT logs in the CloudWatch console**
1. Browse to [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). In the navigation pane, choose **Log groups**.
1. In the **Filter** text box, enter **AWSIotLogsV2** , and then press Enter.
1. Double-click the `AWSIotLogsV2` log group.
1. Choose **Search All**. A complete list of the AWS IoT logs generated for your account is displayed.
1. Choose the expand icon to look at an individual stream.
You can also enter a query in the **Filter events** text box. Here are some interesting queries to try:
+ `{ $.logLevel = "INFO" }`
Find all logs that have a log level of `INFO`.
+ `{ $.status = "Success" }`
Find all logs that have a status of `Success`.
+ `{ $.status = "Success" && $.eventType = "GetThingShadow" }`
Find all logs that have a status of `Success` and an event type of `GetThingShadow`.
For more information about creating filter expressions, see [CloudWatch Logs Queries](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html).
# CloudWatch Logs AWS IoT log entries
Each component of AWS IoT generates its own log entries. Each log entry has an `eventType` that specifies the operation that caused the log entry to be generated. This section describes the log entries generated by the following AWS IoT components.
**Topics**
+ [Message broker log entries](#message-broker-logs)
+ [Server certificate OCSP log entries](#server-ocsp-logs)
+ [Device Shadow log entries](#device-shadow-logs)
+ [Rules engine log entries](#rule-engine-logs)
+ [Job log entries](#job-logs)
+ [Device provisioning log entries](#provision-logs)
+ [Dynamic thing group log entries](#dynamic-group-logs)
+ [Fleet indexing log entries](#fleet-indexing-logs)
+ [Common CloudWatch Logs attributes](#cwl-common-attributes)
## Message broker log entries
The AWS IoT message broker generates log entries for the following events:
**Topics**
+ [Connect log entry](#log-mb-connect)
+ [Disconnect log entry](#log-mb-disconnect)
+ [DeleteConnection log entry](#log-mb-delete-connection)
+ [GetRetainedMessage log entry](#log-mb-get-retain)
+ [ListRetainedMessage log entry](#log-mb-list-retain)
+ [Publish-In log entry](#log-mb-publish-in)
+ [Publish-Out log entry](#log-mb-publish-out)
+ [Queued log entry](#log-mb-queued)
+ [Subscribe log entry](#log-mb-subscribe)
+ [Unsubscribe log entry](#log-mb-unsubscribe)
### Connect log entry
The AWS IoT message broker generates a log entry with an `eventType` of `Connect` when an MQTT client connects.
#### Connect log entry example
```
{
"timestamp": "2017-08-10 15:37:23.476",
"logLevel": "INFO",
"traceId": "20b23f3f-d7f1-feae-169f-82263394fbdb",
"accountId": "123456789012",
"status": "Success",
"eventType": "Connect",
"protocol": "MQTT",
"clientId": "abf27092886e49a8a5c1922749736453",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"sourceIp": "205.251.233.181",
"sourcePort": 13490
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`Connect` log entries contain the following attributes:
clientId
The ID of the client making the request.
principalId
The ID of the principal making the request.
protocol
The protocol used to make the request. Valid values are `MQTT` or `HTTP`.
sourceIp
The IP address where the request originated.
sourcePort
The port where the request originated.
### Disconnect log entry
The AWS IoT message broker generates a log entry with an `eventType` of `Disconnect` when an MQTT client disconnects.
#### Disconnect log entry example
```
{
"timestamp": "2017-08-10 15:37:23.476",
"logLevel": "INFO",
"traceId": "20b23f3f-d7f1-feae-169f-82263394fbdb",
"accountId": "123456789012",
"status": "Success",
"eventType": "Disconnect",
"protocol": "MQTT",
"clientId": "abf27092886e49a8a5c1922749736453",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"sourceIp": "205.251.233.181",
"sourcePort": 13490,
"reason": "DUPLICATE_CLIENT_ID",
"details": "A new connection was established with the same client ID",
"disconnectReason": "CLIENT_INITIATED_DISCONNECT"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`Disconnect` log entries contain the following attributes:
clientId
The ID of the client making the request.
principalId
The ID of the principal making the request.
protocol
The protocol used to make the request. Valid values are `MQTT` or `HTTP`.
sourceIp
The IP address where the request originated.
sourcePort
The port where the request originated.
reason
The reason why the client is disconnecting.
details
A brief explanation of the error.
disconnectReason
The reason why the client is disconnecting.
### DeleteConnection log entry
The AWS IoT message broker generates a log entry with an `eventType` of `DeleteConnection` when an MQTT client connection is deleted.
#### DeleteConnection log entry example
```
{
"timestamp": "2025-08-09 15:37:23.476",
"logLevel": "INFO",
"traceId": "20b23f3f-d7f1-feae-169f-82263394fbdb",
"accountId": "123456789012",
"status": "Success",
"eventType": "DeleteConnection",
"protocol": "HTTP",
"clientId": "abf27092886e49a8a5c1922749736453",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"sourceIp": "205.251.233.181",
"sourcePort": 13490
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`DeleteConnection` log entries contain the following attributes:
clientId
The ID of the client that will be disconnected.
principalId
The ID of the principal making the request. For information about how to identify the principal using the principal ID, see [Compare IAM identities and credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_identity-management.html) in the *IAM User Guide*.
protocol
The protocol used to make the request. The valid value is `HTTP`.
sourceIp
The IP address where the request originated.
sourcePort
The port where the request originated.
### GetRetainedMessage log entry
The AWS IoT message broker generates a log entry with an `eventType` of `GetRetainedMessage` when [https://docs.aws.amazon.com//iot/latest/developerguide/API_iotdata_GetRetainedMessage.html](https://docs.aws.amazon.com//iot/latest/developerguide/API_iotdata_GetRetainedMessage.html) is called.
#### GetRetainedMessage log entry example
```
{
"timestamp": "2017-08-07 18:47:56.664",
"logLevel": "INFO",
"traceId": "1a60d02e-15b9-605b-7096-a9f584a6ad3f",
"accountId": "123456789012",
"status": "Success",
"eventType": "GetRetainedMessage",
"protocol": "HTTP",
"topicName": "a/b/c",
"qos": "1",
"lastModifiedDate": "2017-08-07 18:47:56.664"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`GetRetainedMessage` log entries contain the following attributes:
lastModifiedDate
The Epoch date and time, in milliseconds, when the retained message was stored by AWS IoT.
protocol
The protocol used to make the request. Valid value: `HTTP`.
qos
The Quality of Service (QoS) level used in the publish request. Valid values are `0` or `1`.
topicName
The name of the subscribed topic.
### ListRetainedMessage log entry
The AWS IoT message broker generates a log entry with an `eventType` of `ListRetainedMessage` when [/iot/latest/developerguide/API_iotdata_ListRetainedMessages.html](/iot/latest/developerguide/API_iotdata_ListRetainedMessages.html) is called.
#### ListRetainedMessage log entry example
```
{
"timestamp": "2017-08-07 18:47:56.664",
"logLevel": "INFO",
"traceId": "1a60d02e-15b9-605b-7096-a9f584a6ad3f",
"accountId": "123456789012",
"status": "Success",
"eventType": "ListRetainedMessage",
"protocol": "HTTP"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`ListRetainedMessage` log entries contains the following attribute:
protocol
The protocol used to make the request. Valid value: `HTTP`.
### Publish-In log entry
When the AWS IoT message broker receives an MQTT message, it generates a log entry with an `eventType` of `Publish-In`.
#### Publish-In log entry example
```
{
"timestamp": "2017-08-10 15:39:30.961",
"logLevel": "INFO",
"traceId": "672ec480-31ce-fd8b-b5fb-22e3ac420699",
"accountId": "123456789012",
"status": "Success",
"eventType": "Publish-In",
"protocol": "MQTT",
"topicName": "$aws/things/MyThing/shadow/get",
"clientId": "abf27092886e49a8a5c1922749736453",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"sourceIp": "205.251.233.181",
"sourcePort": 13490,
"retain": "True"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`Publish-In` log entries contain the following attributes:
clientId
The ID of the client making the request.
principalId
The ID of the principal making the request.
protocol
The protocol used to make the request. Valid values are `MQTT` or `HTTP`.
retain
The attribute used when a message has the RETAIN flag set with a value of `True`. If the message doesn't have the RETAIN flag set, this attribute doesn't appear in the log entry. For more information, see [MQTT retained messages](mqtt.md#mqtt-retain) .
sourceIp
The IP address where the request originated.
sourcePort
The port where the request originated.
topicName
The name of the subscribed topic.
### Publish-Out log entry
When the message broker publishes an MQTT message, it generates a log entry with an `eventType` of `Publish-Out`
#### Publish-Out log entry example
```
{
"timestamp": "2017-08-10 15:39:30.961",
"logLevel": "INFO",
"traceId": "672ec480-31ce-fd8b-b5fb-22e3ac420699",
"accountId": "123456789012",
"status": "Success",
"eventType": "Publish-Out",
"protocol": "MQTT",
"topicName": "$aws/things/MyThing/shadow/get",
"clientId": "abf27092886e49a8a5c1922749736453",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"sourceIp": "205.251.233.181",
"sourcePort": 13490
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`Publish-Out` log entries contain the following attributes:
clientId
The ID of the subscribed client that receives messages on that MQTT topic.
principalId
The ID of the principal making the request.
protocol
The protocol used to make the request. Valid values are `MQTT` or `HTTP`.
sourceIp
The IP address where the request originated.
sourcePort
The port where the request originated.
topicName
The name of the subscribed topic.
### Queued log entry
When a device with a persistent session is disconnected, the MQTT message broker stores the device's messages and AWS IoT generates log entries with an eventType of `Queued`. For more information about MQTT persistent sessions, see [MQTT persistent sessions](mqtt.md#mqtt-persistent-sessions) .
#### Queued server error log entry example
```
{
"timestamp": "2022-08-10 15:39:30.961",
"logLevel": "ERROR",
"traceId": "672ec480-31ce-fd8b-b5fb-22e3ac420699",
"accountId": "123456789012",
"topicName": "$aws/things/MyThing/get",
"clientId": "123123123",
"qos": "1",
"protocol": "MQTT",
"eventType": "Queued",
"status": "Failure",
"details": "Server Error"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`Queued` server error log entries contain the following attributes:
clientId
The ID of the client to which the message is queued.
details
**`Server Error`**
A server error prevented the message from being stored.
protocol
The protocol used to make the request. The value will always be `MQTT`.
qos
The Quality of Service (QoS) level of the request. The value will always be 1 because the messages with QoS of 0 aren't stored.
topicName
The name of the subscribed topic.
#### Queued success log entry example
```
{
"timestamp": "2022-08-10 15:39:30.961",
"logLevel": "INFO",
"traceId": "672ec480-31ce-fd8b-b5fb-22e3ac420699",
"accountId": "123456789012",
"topicName": "$aws/things/MyThing/get",
"clientId": "123123123",
"qos": "1",
"protocol": "MQTT",
"eventType": "Queued",
"status": "Success"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`Queued` success log entries contain the following attributes:
clientId
The ID of the client to which the message is queued.
protocol
The protocol used to make the request. The value will always be `MQTT`.
qos
The Quality of Service (QoS) level of the request. The value will always be 1 because the messages with QoS of 0 aren't stored.
topicName
The name of the subscribed topic.
#### Queued throttled log entry example
```
{
"timestamp": "2022-08-10 15:39:30.961",
"logLevel": "ERROR",
"traceId": "672ec480-31ce-fd8b-b5fb-22e3ac420699",
"accountId": "123456789012",
"topicName": "$aws/things/MyThing/get",
"clientId": "123123123",
"qos": "1",
"protocol": "MQTT",
"eventType": "Queued",
"status": "Failure",
"details": "Throttled while queueing offline message"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`Queued` throttled log entries contain the following attributes:
clientId
The ID of the client to which the message is queued.
details
**`Throttled while queueing offline message`**
The client exceeded the ` [Queued messages per second per account](https://docs.aws.amazon.com//general/latest/gr/iot-core.html#genref_queued_messages_per_second_per_account) ` limit, so the message wasn't stored.
protocol
The protocol used to make the request. The value will always be `MQTT`.
qos
The Quality of Service (QoS) level of the request. The value will always be 1 because the messages with QoS of 0 aren't stored.
topicName
The name of the subscribed topic.
### Subscribe log entry
The AWS IoT message broker generates a log entry with an `eventType` of `Subscribe` when an MQTT client subscribes to a topic.
#### MQTT 3 Subscribe log entry example
```
{
"timestamp": "2017-08-10 15:39:04.413",
"logLevel": "INFO",
"traceId": "7aa5c38d-1b49-3753-15dc-513ce4ab9fa6",
"accountId": "123456789012",
"status": "Success",
"eventType": "Subscribe",
"protocol": "MQTT",
"topicName": "$aws/things/MyThing/shadow/#",
"clientId": "abf27092886e49a8a5c1922749736453",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"sourceIp": "205.251.233.181",
"sourcePort": 13490
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`Subscribe` log entries contain the following attributes:
clientId
The ID of the client making the request.
principalId
The ID of the principal making the request.
protocol
The protocol used to make the request. The value will always be `MQTT`.
sourceIp
The IP address where the request originated.
sourcePort
The port where the request originated.
topicName
The name of the subscribed topic.
#### MQTT 5 Subscribe log entry example
```
{
"timestamp": "2022-11-30 16:24:15.628",
"logLevel": "INFO",
"traceId": "7aa5c38d-1b49-3753-15dc-513ce4ab9fa6",
"accountId": "123456789012",
"status": "Success",
"eventType": "Subscribe",
"protocol": "MQTT",
"topicName": "test/topic1,$invalid/reserved/topic",
"subscriptions": [
{
"topicName": "test/topic1",
"reasonCode": 1
},
{
"topicName": "$invalid/reserved/topic",
"reasonCode": 143
}
],
"clientId": "abf27092886e49a8a5c1922749736453",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"sourceIp": "205.251.233.181",
"sourcePort": 13490
}
```
For MQTT 5 Subscribe operations, in addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) and the [MQTT 3 Subscribe log entry attributes](#log-mb-connect.example.subscribe), MQTT 5 `Subscribe` log entries contain the following attribute:
subscriptions
A list of mappings between the requested topics in the Subscribe request and the individual MQTT 5 reason code. For more information, see [MQTT reason codes](https://docs.aws.amazon.com//iot/latest/developerguide/mqtt.html#mqtt5-reason-codes).
### Unsubscribe log entry
The AWS IoT message broker generates a log entry with an `eventType` of `Unsubscribe` when an MQTT client unsubscribes to an MQTT topic.
#### MQTT unsubscribe log entry example
```
{
"timestamp": "2024-08-20 22:53:32.844",
"logLevel": "INFO",
"traceId": "db6bd09a-2c3f-1cd2-27cc-fd6b1ce03b58",
"accountId": "123456789012",
"status": "Success",
"eventType": "Unsubscribe",
"protocol": "MQTT",
"clientId": "abf27092886e49a8a5c1922749736453",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"sourceIp": "205.251.233.181",
"sourcePort": 13490
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`Unsubscribe` log entries contain the following attributes:
protocol
The protocol used to make the request. The value will always be `MQTT`.
clientId
The ID of the client making the request.
principalId
The ID of the principal making the request.
sourceIp
The IP address where the request originated.
sourcePort
The port where the request originated.
## Server certificate OCSP log entries
AWS IoT Core generates log entries for the following event:
**Topics**
+ [RetrieveOCSPStapleData log entry](#log-retrieve-ocsp-staple)
+ [RetrieveOCSPStapleData log entry for private endpoints](#log-retrieve-ocsp-staple-private-endpoint)
### RetrieveOCSPStapleData log entry
AWS IoT Core generates a log entry with an `eventType` of `RetrieveOCSPStapleData` when the server retrieves the OCSP staple data.
#### RetrieveOCSPStapleData log entry examples
The following is a log entry example of `Success`.
```
{
"timestamp": "2024-01-30 15:39:30.961",
"logLevel": "INFO",
"traceId": "180532b7-0cc7-057b-687a-5ca1824838f5",
"accountId": "123456789012",
"status": "Success",
"eventType": "RetrieveOCSPStapleData",
"domainConfigName": "test-domain-config-name",
"connectionDetails": {
"httpStatusCode": "200",
"ocspResponderUri": "http://ocsp.example.com",
"sourceIp": "205.251.233.181",
"targetIp": "250.15.5.3"
},
"ocspRequestDetails": {
"requesterName": "iot.amazonaws.com",
"requestCertId": "30:3A:30:09:06:05:2B:0E:03:02:1A:05:00:04:14:9C:FF:90:A1:97:B0:4D:6C:01:B9:69:96:D8:3E:E7:A2:51:7F:30:C4:04:14:7C:84:78:AE:12:58:71:38:0C:65:FC:17:77:7D:14:DD:69:73:71:46:02:01:01"
},
"ocspResponseDetails": {
"responseCertId": "30:3A:30:09:06:05:2B:0E:03:02:1A:05:00:04:14:9C:FF:90:A1:97:B0:4D:6C:01:B9:69:96:D8:3E:E7:A2:51:7F:30:C4:04:14:7C:84:78:AE:12:58:71:38:0C:65:FC:17:77:7D:14:DD:69:73:71:46:02:01:01",
"ocspResponseStatus": "successful",
"certStatus": "good",
"signature": "4C:6F:63:61:6C:20:52:65:73:70:6F:6E:64:65:72:20:53:69:67:6E:61:74:75:72:65",
"thisUpdateTime": "Jan 31 01:21:02 2024 UTC",
"nextUpdateTime": "Feb 02 00:21:02 2024 UTC",
"producedAtTime": "Jan 31 01:37:03 2024 UTC",
"stapledDataPayloadSize": "XXX"
}
}
```
The following is a log entry example of `Failure`.
```
{
"timestamp": "2024-01-30 15:39:30.961",
"logLevel": "ERROR",
"traceId": "180532b7-0cc7-057b-687a-5ca1824838f5",
"accountId": "123456789012",
"status": "Failure",
"reason": "A non 2xx HTTP response was received from the OCSP responder.",
"eventType": "RetrieveOCSPStapleData",
"domainConfigName": "test-domain-config-name",
"connectionDetails": {
"httpStatusCode": "444",
"ocspResponderUri": "http://ocsp.example.com",
"sourceIp": "205.251.233.181",
"targetIp": "250.15.5.3"
},
"ocspRequestDetails": {
"requesterName": "iot.amazonaws.com",
"requestCertId": "30:3A:30:09:06:05:2B:0E:03:02:1A:05:00:04:14:9C:FF:90:A1:97:B0:4D:6C:01:B9:69:96:D8:3E:E7:A2:51:7F:30:C4:04:14:7C:84:78:AE:12:58:71:38:0C:65:FC:17:77:7D:14:DD:69:73:71:46:02:01:01"
}
}
```
For the `RetrieveOCSPStaple` operation, in addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) , the log entries contain the following attributes:
reason
The reason why the operation fails.
domainConfigName
The name of your domain configuration.
connectionDetails
A brief explanation of the connection details.
+ httpStatusCode
HTTP status codes that are returned by the OCSP responder in response to the client's request made to the server.
+ ocspResponderUri
The OCSP responder URI that AWS IoT Core fetches from the server certificate.
+ sourceIp
The source IP address of the AWS IoT Core server.
+ targetIp
The target IP address of the OCSP responder.
ocspRequestDetails
Details of the OCSP request.
+ requesterName
The identifier for the AWS IoT Core server that sends a request to the OCSP responder.
+ requestCertId
The certificate ID of the request. This is the ID of the certificate for which the OCSP response is being requested.
ocspResponseDetails
Details of the OCSP response.
+ responseCertId
The certificate ID of the OCSP response.
+ ocspResponseStatus
The status of the OCSP response.
+ certStatus
The status of the certificate.
+ signature
The signature that's applied to the response by a trusted entity.
+ thisUpdateTime
The time at which the status being indicated is known to be correct.
+ nextUpdateTime
The time at or before which newer information will be available about the status of the certificate.
+ producedAtTime
The time at which the OCSP responder signed this response.
+ stapledDataPayloadSize
The payload size of the stapled data.
### RetrieveOCSPStapleData log entry for private endpoints
AWS IoT Core generates a log entry with an `eventType` of `RetrieveOCSPStapleData` when the server retrieves the OCSP staple data.
#### RetrieveOCSPStapleData log entry examples for private endpoints
The following is a log entry example of `Success`.
```
{
"timestamp": "2024-01-30 15:39:30.961",
"logLevel": "INFO",
"traceId": "180532b7-0cc7-057b-687a-5ca1824838f5",
"accountId": "123456789012",
"status": "Success",
"eventType": "RetrieveOCSPStapleData",
"domainConfigName": "test-domain-config-name",
"lambdaDetails": {
"lambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:my-function",
"sourceArn": "arn:aws:iot:us-west-2:123456789012:domainconfiguration/testDomainConfigure/6bzfg"
},
"authorizedResponderArn": "arn:aws:acm:us-west-2:123456789012:certificate/certificate_ID",
"ocspRequestDetails": {
"requesterName": "iot.amazonaws.com",
"requestCertId": "30:3A:30:09:06:05:2B:0E:03:02:1A:05:00:04:14:9C:FF:90:A1:97:B0:4D:6C:01:B9:69:96:D8:3E:E7:A2:51:7F:30:C4:04:14:7C:84:78:AE:12:58:71:38:0C:65:FC:17:77:7D:14:DD:69:73:71:46:02:01:01"
},
"ocspResponseDetails": {
"responderId": "04:C1:3F:8F:27:D6:49:13:F8:DE:B2:36:9D:85:8E:F8:31:3B:A6:D0"
"responseCertId": "30:3A:30:09:06:05:2B:0E:03:02:1A:05:00:04:14:9C:FF:90:A1:97:B0:4D:6C:01:B9:69:96:D8:3E:E7:A2:51:7F:30:C4:04:14:7C:84:78:AE:12:58:71:38:0C:65:FC:17:77:7D:14:DD:69:73:71:46:02:01:01",
"ocspResponseStatus": "successful",
"certStatus": "good",
"signature": "4C:6F:63:61:6C:20:52:65:73:70:6F:6E:64:65:72:20:53:69:67:6E:61:74:75:72:65",
"thisUpdateTime": "Jan 31 01:21:02 2024 UTC",
"nextUpdateTime": "Feb 02 00:21:02 2024 UTC",
"producedAtTime": "Jan 31 01:37:03 2024 UTC",
"stapledDataPayloadSize": "XXX"
}
}
```
The following is a log entry example of `Failure`.
```
{
"timestamp": "2024-01-30 15:39:30.961",
"logLevel": "ERROR",
"traceId": "180532b7-0cc7-057b-687a-5ca1824838f5",
"accountId": "123456789012",
"status": "Failure",
"reason": "The payload returned by the Lambda function exceeds the maximum response size of 7 kilobytes.",
"eventType": "RetrieveOCSPStapleData",
"domainConfigName": "test-domain-config-name",
"lambdaDetails": {
"lambdaArn": "arn:aws:lambda:us-west-2:123456789012:function:my-function",
"sourceArn": "arn:aws:iot:us-west-2:123456789012:domainconfiguration/testDomainConfigure/6bzfg"
},
"authorizedResponderArn": "arn:aws:acm:us-west-2:123456789012:certificate/certificate_ID",
"ocspRequestDetails": {
"requesterName": "iot.amazonaws.com",
"requestCertId": "30:3A:30:09:06:05:2B:0E:03:02:1A:05:00:04:14:9C:FF:90:A1:97:B0:4D:6C:01:B9:69:96:D8:3E:E7:A2:51:7F:30:C4:04:14:7C:84:78:AE:12:58:71:38:0C:65:FC:17:77:7D:14:DD:69:73:71:46:02:01:01"
}
}
```
For the `RetrieveOCSPStaple` operation, in addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) and the attributes in [RetrieveOCSPStapleData log entry](https://docs.aws.amazon.com//iot/latest/developerguide/cwl-format.html#log-retrieve-ocsp-staple), the log entries for private endpoints contain the following attributes:
lambdaDetails
Details of the Lambda function.
+ lambdaArn
The ARN of the Lambda function.
+ sourceArn
The ARN of the domain configuration.
authorizedResponderArn
The ARN of the authorizer responder if there is one configured in the domain configuration.
## Device Shadow log entries
The AWS IoT Device Shadow service generates log entries for the following events:
**Topics**
+ [DeleteThingShadow log entry](#log-shadow-delete-thing-shadow)
+ [GetThingShadow log entry](#log-shadow-get-thing-shadow)
+ [UpdateThingShadow log entry](#log-shadow-update-thing-shadow)
### DeleteThingShadow log entry
The Device Shadow service generates a log entry with an `eventType` of `DeleteThingShadow` when a request to delete a device's shadow is received.
#### DeleteThingShadow log entry example
```
{
"timestamp": "2017-08-07 18:47:56.664",
"logLevel": "INFO",
"traceId": "1a60d02e-15b9-605b-7096-a9f584a6ad3f",
"accountId": "123456789012",
"status": "Success",
"eventType": "DeleteThingShadow",
"protocol": "MQTT",
"deviceShadowName": "Jack",
"topicName": "$aws/things/Jack/shadow/delete"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`DeleteThingShadow` log entries contain the following attributes:
deviceShadowName
The name of the shadow to update.
protocol
The protocol used to make the request. Valid values are `MQTT` or `HTTP`.
topicName
The name of the topic on which the request was published.
### GetThingShadow log entry
The Device Shadow service generates a log entry with an `eventType` of `GetThingShadow` when a get request for a shadow is received.
#### GetThingShadow log entry example
```
{
"timestamp": "2017-08-09 17:56:30.941",
"logLevel": "INFO",
"traceId": "b575f19a-97a2-cf72-0ed0-c64a783a2504",
"accountId": "123456789012",
"status": "Success",
"eventType": "GetThingShadow",
"protocol": "MQTT",
"deviceShadowName": "MyThing",
"topicName": "$aws/things/MyThing/shadow/get"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`GetThingShadow` log entries contain the following attributes:
deviceShadowName
The name of the requested shadow.
protocol
The protocol used to make the request. Valid values are `MQTT` or `HTTP`.
topicName
The name of the topic on which the request was published.
### UpdateThingShadow log entry
The Device Shadow service generates a log entry with an `eventType` of `UpdateThingShadow` when a request to update a device's shadow is received.
#### UpdateThingShadow log entry example
```
{
"timestamp": "2017-08-07 18:43:59.436",
"logLevel": "INFO",
"traceId": "d0074ba8-0c4b-a400-69df-76326d414c28",
"accountId": "123456789012",
"status": "Success",
"eventType": "UpdateThingShadow",
"protocol": "MQTT",
"deviceShadowName": "Jack",
"topicName": "$aws/things/Jack/shadow/update"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`UpdateThingShadow` log entries contain the following attributes:
deviceShadowName
The name of the shadow to update.
protocol
The protocol used to make the request. Valid values are `MQTT` or `HTTP`.
topicName
The name of the topic on which the request was published.
## Rules engine log entries
The AWS IoT rules engine generates logs for the following events:
**Topics**
+ [FunctionExecution log entry](#log-rules-fn-exec)
+ [RuleExecution log entry](#log-rules-rule-ex)
+ [RuleMatch log entry](#log-rules-rule-match)
+ [RuleExecutionThrottled log entry](#log-rules-rule-msg-throttled)
+ [RuleNotFound log entry](#log-rules-rule-not-found)
+ [StartingRuleExecution log entry](#log-rules-start-rule-ex)
### FunctionExecution log entry
The rules engine generates a log entry with an `eventType` of `FunctionExecution` when a rule's SQL query calls an external function. An external function is called when a rule's action makes an HTTP request to AWS IoT or another web service (for example, calling `get_thing_shadow` or `machinelearning_predict`).
#### FunctionExecution log entry example
```
{
"timestamp": "2017-07-13 18:33:51.903",
"logLevel": "DEBUG",
"traceId": "180532b7-0cc7-057b-687a-5ca1824838f5",
"status": "Success",
"eventType": "FunctionExecution",
"clientId": "N/A",
"topicName":"rules/test",
"ruleName": "ruleTestPredict",
"ruleAction": "MachinelearningPredict",
"resources": {
"ModelId": "predict-model"
},
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`FunctionExecution` log entries contain the following attributes:
clientId
`N/A` for `FunctionExecution` logs.
principalId
The ID of the principal making the request.
resources
A collection of resources used by the rule's actions.
ruleName
The name of the matching rule.
topicName
The name of the subscribed topic.
### RuleExecution log entry
When the AWS IoT rules engine triggers a rule's action, it generates a `RuleExecution` log entry.
#### RuleExecution log entry example
```
{
"timestamp": "2017-08-10 16:32:46.070",
"logLevel": "INFO",
"traceId": "30aa7ccc-1d23-0b97-aa7b-76196d83537e",
"accountId": "123456789012",
"status": "Success",
"eventType": "RuleExecution",
"clientId": "abf27092886e49a8a5c1922749736453",
"topicName": "rules/test",
"ruleName": "JSONLogsRule",
"ruleAction": "RepublishAction",
"resources": {
"RepublishTopic": "rules/republish"
},
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167"
}
```
#### RuleExecution with batching log entry example
```
{
"logLevel": "INFO",
"accountId": "123456789012",
"status": "Success",
"eventType": "RuleExecution",
"ruleName": "rule_test",
"ruleAction": "HttpAction",
"resources": {
"Url": "https://example.com",
"ConfirmationUrl": "https://example.com"
},
"details": "HttpAction made a request to the specified endpoint",
"batchDetails": {
"timestamps": [
"1234567890123",
"1234567890123",
"1234567890123"
],
"traceIds": [
"30aa7ccc-1d23-0b97-aa7b-76196d83537e",
"30aa7ccc-1d23-0b97-aa7b-76196d83537c",
"30aa7ccc-1d23-0b97-aa7b-76196d83537d"
],
"clientIds": [
"N/A",
"N/A",
"N/A"
],
"topicNames": [
"topic/ruletest",
"topic/ruletest",
"topic/ruletest"
],
"principalIds": [
"145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167"
],
"batchSize": 3,
"batchSizeInBytes": 114
}
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes), `RuleExecution` log entries contain the following attributes:
clientId
The ID of the client making the request.
principalId
The ID of the principal making the request.
resources
A collection of resources used by the rule's actions.
ruleAction
The name of the action triggered.
ruleName
The name of the matching rule.
topicName
The name of the subscribed topic.
### RuleMatch log entry
The AWS IoT rules engine generates a log entry with an `eventType` of `RuleMatch` when the message broker receives a message that matches a rule.
#### RuleMatch log entry example
```
{
"timestamp": "2017-08-10 16:32:46.002",
"logLevel": "INFO",
"traceId": "30aa7ccc-1d23-0b97-aa7b-76196d83537e",
"accountId": "123456789012",
"status": "Success",
"eventType": "RuleMatch",
"clientId": "abf27092886e49a8a5c1922749736453",
"topicName": "rules/test",
"ruleName": "JSONLogsRule",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`RuleMatch` log entries contain the following attributes:
clientId
The ID of the client making the request.
principalId
The ID of the principal making the request.
ruleName
The name of the matching rule.
topicName
The name of the subscribed topic.
### RuleExecutionThrottled log entry
When an execution is throttled, the AWS IoT rules engine generates a log entry with an `eventType` of `RuleExecutionThrottled`.
#### RuleExecutionThrottled log entry example
```
{
"timestamp": "2017-10-04 19:25:46.070",
"logLevel": "ERROR",
"traceId": "30aa7ccc-1d23-0b97-aa7b-76196d83537e",
"accountId": "123456789012",
"status": "Failure",
"eventType": "RuleExecutionThrottled",
"clientId": "abf27092886e49a8a5c1922749736453",
"topicName": "$aws/rules/example_rule",
"ruleName": "example_rule",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"reason": "RuleExecutionThrottled",
"details": "Exection of Rule example_rule throttled"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`RuleExecutionThrottled` log entries contain the following attributes:
clientId
The ID of the client making the request.
details
A brief explanation of the error.
principalId
The ID of the principal making the request.
reason
The string "RuleExecutionThrottled".
ruleName
The name of the rule to be triggered.
topicName
The name of the topic that was published.
### RuleNotFound log entry
When the AWS IoT rules engine cannot find a rule with a given name, it generates a log entry with an `eventType` of `RuleNotFound`.
#### RuleNotFound log entry example
```
{
"timestamp": "2017-10-04 19:25:46.070",
"logLevel": "ERROR",
"traceId": "30aa7ccc-1d23-0b97-aa7b-76196d83537e",
"accountId": "123456789012",
"status": "Failure",
"eventType": "RuleNotFound",
"clientId": "abf27092886e49a8a5c1922749736453",
"topicName": "$aws/rules/example_rule",
"ruleName": "example_rule",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167",
"reason": "RuleNotFound",
"details": "Rule example_rule not found"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`RuleNotFound` log entries contain the following attributes:
clientId
The ID of the client making the request.
details
A brief explanation of the error.
principalId
The ID of the principal making the request.
reason
The string "RuleNotFound".
ruleName
The name of the rule that could not be found.
topicName
The name of the topic that was published.
### StartingRuleExecution log entry
When the AWS IoT rules engine starts to trigger a rule's action, it generates a log entry with an `eventType` of `StartingRuleExecution`.
#### StartingRuleExecution log entry example
```
{
"timestamp": "2017-08-10 16:32:46.002",
"logLevel": "DEBUG",
"traceId": "30aa7ccc-1d23-0b97-aa7b-76196d83537e",
"accountId": "123456789012",
"status": "Success",
"eventType": "StartingRuleExecution",
"clientId": "abf27092886e49a8a5c1922749736453",
"topicName": "rules/test",
"ruleName": "JSONLogsRule",
"ruleAction": "RepublishAction",
"principalId": "145179c40e2219e18a909d896a5340b74cf97a39641beec2fc3eeafc5a932167"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`rule-` log entries contain the following attributes:
clientId
The ID of the client making the request.
principalId
The ID of the principal making the request.
ruleAction
The name of the action triggered.
ruleName
The name of the matching rule.
topicName
The name of the subscribed topic.
## Job log entries
The AWS IoT Job service generates log entries for the following events. Log entries are generated when an MQTT or HTTP request is received from the device.
**Topics**
+ [DescribeJobExecution log entry](#log-job-describe-job-ex)
+ [GetPendingJobExecution log entry](#log-job-get-pending-job-ex)
+ [ReportFinalJobExecutionCount log entry](#log-job-report-final-job-ex-count)
+ [StartNextPendingJobExecution log entry](#log-job-start-next-pending-job-ex)
+ [UpdateJobExecution log entry](#log-job-update-job-ex)
### DescribeJobExecution log entry
The AWS IoT Jobs service generates a log entry with an `eventType` of `DescribeJobExecution` when the service receives a request to describe a job execution.
#### DescribeJobExecution log entry example
```
{
"timestamp": "2017-08-10 19:13:22.841",
"logLevel": "DEBUG",
"accountId": "123456789012",
"status": "Success",
"eventType": "DescribeJobExecution",
"protocol": "MQTT",
"clientId": "thingOne",
"jobId": "002",
"topicName": "$aws/things/thingOne/jobs/002/get",
"clientToken": "myToken",
"details": "The request status is SUCCESS."
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`GetJobExecution` log entries contain the following attributes:
clientId
The ID of the client making the request.
clientToken
A unique, case-sensitive identifier to ensure the idempotency of the request. For more information, see [How to Ensure Idempotency](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html).
details
Other information from the Jobs service.
jobId
The job ID for the job execution.
protocol
The protocol used to make the request. Valid values are `MQTT` or `HTTP`.
topicName
The topic used to make the request.
### GetPendingJobExecution log entry
The AWS IoT Jobs service generates a log entry with an `eventType` of `GetPendingJobExecution` when the service receives a job execution request.
#### GetPendingJobExecution log entry example
```
{
"timestamp": "2018-06-13 17:45:17.197",
"logLevel": "DEBUG",
"accountId": "123456789012",
"status": "Success",
"eventType": "GetPendingJobExecution",
"protocol": "MQTT",
"clientId": "299966ad-54de-40b4-99d3-4fc8b52da0c5",
"topicName": "$aws/things/299966ad-54de-40b4-99d3-4fc8b52da0c5/jobs/get",
"clientToken": "24b9a741-15a7-44fc-bd3c-1ff2e34e5e82",
"details": "The request status is SUCCESS."
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`GetPendingJobExecution` log entries contain the following attributes:
clientId
The ID of the client making the request.
clientToken
A unique, case sensitive identifier to ensure the idempotency of the request. For more information, see [How to Ensure Idempotency](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html).
details
Other information from the Jobs service.
protocol
The protocol used to make the request. Valid values are `MQTT` or `HTTP`.
topicName
The name of the subscribed topic.
### ReportFinalJobExecutionCount log entry
The AWS IoT Jobs service generates a log entry with an `entryType` of `ReportFinalJobExecutionCount` when a job is completed.
#### ReportFinalJobExecutionCount log entry example
```
{
"timestamp": "2017-08-10 19:44:16.776",
"logLevel": "INFO",
"accountId": "123456789012",
"status": "Success",
"eventType": "ReportFinalJobExecutionCount",
"jobId": "002",
"details": "Job 002 completed. QUEUED job execution count: 0 IN_PROGRESS job execution count: 0 FAILED job execution count: 0 SUCCEEDED job execution count: 1 CANCELED job execution count: 0 REJECTED job execution count: 0 REMOVED job execution count: 0"
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`ReportFinalJobExecutionCount` log entries contain the following attributes:
details
Other information from the Jobs service.
jobId
The job ID for the job execution.
### StartNextPendingJobExecution log entry
When it receives a request to start the next pending job execution, the AWS IoT Jobs service generates a log entry with an `eventType` of `StartNextPendingJobExecution`.
#### StartNextPendingJobExecution log entry example
```
{
"timestamp": "2018-06-13 17:49:51.036",
"logLevel": "DEBUG",
"accountId": "123456789012",
"status": "Success",
"eventType": "StartNextPendingJobExecution",
"protocol": "MQTT",
"clientId": "95c47808-b1ca-4794-bc68-a588d6d9216c",
"topicName": "$aws/things/95c47808-b1ca-4794-bc68-a588d6d9216c/jobs/start-next",
"clientToken": "bd7447c4-3a05-49f4-8517-dd89b2c68d94",
"details": "The request status is SUCCESS."
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`StartNextPendingJobExecution` log entries contain the following attributes:
clientId
The ID of the client making the request.
clientToken
A unique, case sensitive identifier to ensure the idempotency of the request. For more information, see [How to Ensure Idempotency](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html).
details
Other information from the Jobs service.
protocol
The protocol used to make the request. Valid values are `MQTT` or `HTTP`.
topicName
The topic used to make the request.
### UpdateJobExecution log entry
The AWS IoT Jobs service generates a log entry with an `eventType` of `UpdateJobExecution` when the service receives a request to update a job execution.
#### UpdateJobExecution log entry example
```
{
"timestamp": "2017-08-10 19:25:14.758",
"logLevel": "DEBUG",
"accountId": "123456789012",
"status": "Success",
"eventType": "UpdateJobExecution",
"protocol": "MQTT",
"clientId": "thingOne",
"jobId": "002",
"topicName": "$aws/things/thingOne/jobs/002/update",
"clientToken": "myClientToken",
"versionNumber": "1",
"details": "The destination status is IN_PROGRESS. The request status is SUCCESS."
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`UpdateJobExecution` log entries contain the following attributes:
clientId
The ID of the client making the request.
clientToken
A unique, case sensitive identifier to ensure the idempotency of the request. For more information, see [How to Ensure Idempotency](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html).
details
Other information from the Jobs service.
jobId
The job ID for the job execution.
protocol
The protocol used to make the request. Valid values are `MQTT` or `HTTP`.
topicName
The topic used to make the request.
versionNumber
The version of the job execution.
## Device provisioning log entries
The AWS IoT Device Provisioning service generates logs for the following events.
**Topics**
+ [GetDeviceCredentials log entry](#log-provision-get-device-credentials)
+ [ProvisionDevice log entry](#log-provision-provision-device)
### GetDeviceCredentials log entry
The AWS IoT Device Provisioning service generates a log entry with an `eventType` of `GetDeviceCredential` when a client calls `GetDeviceCredential`.
#### GetDeviceCredentials log entry example
```
{
"timestamp" : "2019-02-20 20:31:22.932",
"logLevel" : "INFO",
"traceId" : "8d9c016f-6cc7-441e-8909-7ee3d5563405",
"accountId" : "123456789101",
"status" : "Success",
"eventType" : "GetDeviceCredentials",
"deviceCertificateId" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"details" : "Additional details about this log."
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`GetDeviceCredentials` log entries contain the following attributes:
details
A brief explanation of the error.
deviceCertificateId
The ID of the device certificate.
### ProvisionDevice log entry
The AWS IoT Device Provisioning service generates a log entry with an `eventType` of `ProvisionDevice` when a client calls `ProvisionDevice`.
#### ProvisionDevice log entry example
```
{
"timestamp" : "2019-02-20 20:31:22.932",
"logLevel" : "INFO",
"traceId" : "8d9c016f-6cc7-441e-8909-7ee3d5563405",
"accountId" : "123456789101",
"status" : "Success",
"eventType" : "ProvisionDevice",
"provisioningTemplateName" : "myTemplate",
"deviceCertificateId" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"details" : "Additional details about this log."
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) ,`ProvisionDevice` log entries contain the following attributes:
details
A brief explanation of the error.
deviceCertificateId
The ID of the device certificate.
provisioningTemplateName
The name of the provisioning template.
## Dynamic thing group log entries
AWS IoT Dynamic Thing Groups generate logs for the following event.
**Topics**
+ [AddThingToDynamicThingGroupsFailed log entry](#log-dynthing-add-thing-to-dynamic-thing-groups-failed)
### AddThingToDynamicThingGroupsFailed log entry
When AWS IoT was not able to add a thing to the specified dynamic groups, it generates a log entry with an `eventType` of `AddThingToDynamicThingGroupsFailed`. This happens when a thing met the criteria to be in the dynamic thing group; however, it could not be added to the dynamic group or it was removed from the dynamic group. This can happen because:
+ The thing already belongs to the maximum number of groups.
+ The **--override-dynamic-groups** option was used to add the thing to a static thing group. It was removed from a dynamic thing group to make that possible.
For more information, see [Dynamic Thing Group Limitations and Conflicts](dynamic-thing-groups.md#dynamic-thing-group-limitations).
#### AddThingToDynamicThingGroupsFailed log entry example
This example shows the log entry of an `AddThingToDynamicThingGroupsFailed` error. In this example, *TestThing* met the criteria to be in the dynamic thing groups listed in `dynamicThingGroupNames`, but could not be added to those dynamic groups, as described in `reason`.
```
{
"timestamp": "2020-03-16 22:24:43.804",
"logLevel": "ERROR",
"traceId": "70b1f2f5-d95e-f897-9dcc-31e68c3e1a30",
"accountId": "57EXAMPLE833",
"status": "Failure",
"eventType": "AddThingToDynamicThingGroupsFailed",
"thingName": "TestThing",
"dynamicThingGroupNames": [
"DynamicThingGroup11",
"DynamicThingGroup12",
"DynamicThingGroup13",
"DynamicThingGroup14"
],
"reason": "The thing failed to be added to the given dynamic thing group(s) because the thing already belongs to the maximum allowed number of groups."
}
```
In addition to the [Common CloudWatch Logs attributes](#cwl-common-attributes) , `AddThingToDynamicThingGroupsFailed` log entries contain the following attributes:
dynamicThingGroupNames
An array of the dynamic thing groups to which the thing could not be added.
reason
The reason why the thing could not be added to the dynamic thing groups.
thingName
The name of the thing that could not be added to a dynamic thing group.
## Fleet indexing log entries
AWS IoT fleet indexing generates log entries for the following events.
**Topics**
+ [NamedShadowCountForDynamicGroupQueryLimitExceeded log entry](#log-named-shadow-dynamic-group)
### NamedShadowCountForDynamicGroupQueryLimitExceeded log entry
A maximum of 25 named shadows per thing are processed for query terms that are not data source specific in dynamic groups. When this limit is breached for a thing, the `NamedShadowCountForDynamicGroupQueryLimitExceeded` event type will be emitted.
#### NamedShadowCountForDynamicGroupQueryLimitExceeded log entry example
This example shows the log entry of a `NamedShadowCountForDynamicGroupQueryLimitExceeded` error. In this example, all-values based `DynamicGroup` results can be inaccurate, as described in the `reason` field.
```
{
"timestamp": "2020-03-16 22:24:43.804",
"logLevel": "ERROR",
"traceId": "70b1f2f5-d95e-f897-9dcc-31e68c3e1a30",
"accountId": "571032923833",
"status": "Failure",
"eventType": "NamedShadowCountForDynamicGroupQueryLimitExceeded",
"thingName": "TestThing",
"reason": "A maximum of 25 named shadows per thing are processed for non-data source specific query terms in dynamic groups."
}
```
## Common CloudWatch Logs attributes
All CloudWatch Logs log entries include these attributes:
accountId
Your AWS account ID.
eventType
The event type for which the log was generated. The value of the event type depends on the event that generated the log entry. Each log entry description includes the value of `eventType` for that log entry.
logLevel
The log level being used. For more information, see [Log levels](configure-logging.md#log-level) .
status
The status of the request.
timestamp
The human-readable UTC timestamp of when the client connected to the AWS IoT message broker.
traceId
A randomly generated identifier that can be used to correlate all logs for a specific request.
# Upload device-side logs to Amazon CloudWatch
You can upload historical, device-side logs into Amazon CloudWatch to monitor and analyze a device's activity in the field. Device-side logs can include system, application, and device logs files. This process uses a CloudWatch Logs rules action parameter to publish device-side logs into a customer-defined [log group](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html).
## How it works
The process begins when an AWS IoT device sends MQTT messages containing formatted log files to an AWS IoT topic. An AWS IoT rule monitors the message topic and sends the log files to a CloudWatch Logs group that you define. You can then review and analyze the information.
**Topics**
+ [MQTT topics](#upload-mqtt-topics-overview)
+ [Rule action](#upload-rule-action-overview)
### MQTT topics
Choose an MQTT topic name space that you will use to publish the logs. We recommend using this format for the common topic space, `$aws/rules/things/thing_name/logs`, and this format for error topics, `$aws/rules/things/thing_name/logs/errors`. The naming structure for logs and error topics is recommended, but not required. For more information, see [Designing MQTT Topics for AWS IoT Core](https://docs.aws.amazon.com/whitepapers/latest/designing-mqtt-topics-aws-iot-core/designing-mqtt-topics-aws-iot-core.html).
By using the recommended common topic space, you utilize AWS IoT Basic Ingest reserved topics. AWS IoT Basic Ingest securely sends device data to the AWS services that are supported by AWS IoT rule actions. It removes the publish/subscribe message broker from the ingestion path, making it more cost effective. For more information, see [Reducing messaging costs with Basic Ingest](https://docs.aws.amazon.com/iot/latest/developerguide/iot-basic-ingest.html).
If you use batchMode to upload log files, your messages must follow a specific format that includes a UNIX timestamp and message. For more information, see the [MQTT message format requirements for batchMode](https://docs.aws.amazon.com/iot/latest/developerguide/cloudwatch-logs-rule-action.html#cloudwatch-logs-rule-action-message-format) topic within [CloudWatch Logs rule action](https://docs.aws.amazon.com/iot/latest/developerguide/cloudwatch-logs-rule-action.html).
### Rule action
When AWS IoT receives the MQTT messages from the client devices, an AWS IoT rule monitors the customer-defined topic and publishes the contents into a CloudWatch log group that you define. This process uses a CloudWatch Logs rule action to monitor MQTT for batches of log files. For more information, see the [CloudWatch Logs](https://docs.aws.amazon.com/iot/latest/developerguide/cloudwatch-logs-rule-action.html) AWS IoT rule action.
#### Batch mode
`batchMode` is a Boolean parameter within the AWS IoT CloudWatch Logs rule action. This parameter is optional and is off (`false`) by default. To upload device-side log files in batches, you must turn this parameter on (`true`) when you create the AWS IoT rule. For more information, see [CloudWatch Logs](https://docs.aws.amazon.com/iot/latest/developerguide/cloudwatch-logs-rule-action.html) in the [AWS IoT rule actions](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html) section.
# Uploading device-side logs by using AWS IoT rules
You can use the AWS IoT rules engine to upload log records from existing device-side log files (system, application, and device-client logs) to Amazon CloudWatch. When device-side logs are published to an MQTT topic, the CloudWatch Logs rules action transfers the messages to CloudWatch Logs. This process outlines how to upload device logs in batches using the rules action `batchMode` parameter turned on (set to `true`).
To begin uploading device-side logs to CloudWatch, complete the following prerequisites.
## Prerequisites
Before you begin, do the following:
+ Create at least one target IoT device that's registered with AWS IoT Core as an AWS IoT thing. For more information, see [Create a thing object](https://docs.aws.amazon.com/iot/latest/developerguide/create-iot-resources.html#create-aws-thing).
+ Determine the MQTT topic space for ingestion and errors. For more information about MQTT topics and recommended naming conventions, see the [MQTT topics](upload-device-logs-to-cloudwatch.md#upload-mqtt-topics-overview) [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/upload-device-logs-to-cloudwatch.html#upload-mqtt-topics-overview) section in [Upload device-side logs to Amazon CloudWatch](https://docs.aws.amazon.com/iot/latest/developerguide/upload-device-logs-to-cloudwatch.html).
For more information about these prerequisites, see [Upload device-side logs to CloudWatch](https://docs.aws.amazon.com/iot/latest/developerguide/upload-device-logs-to-cloudwatch).
## Creating a CloudWatch log group
To create a CloudWatch log group, complete the following steps. Choose the appropriate tab depending on whether you prefer to perform the steps through the AWS Management Console or the AWS Command Line Interface (AWS CLI).
------
#### [ AWS Management Console ]
**To create a CloudWatch log group by using the AWS Management Console**
1. Open the AWS Management Console and navigate to [CloudWatch](https://console.aws.amazon.com//cloudwatch).
1. On the navigation bar, choose **Logs**, and then **Log groups**.
1. Choose **Create log group**.
1. Update the **Log group name** and, optionally, update the **Retention setting** fields.
1. Choose **Create**.
------
#### [ AWS CLI ]
**To create a CloudWatch log group by using the AWS CLI**
1. To create the log group, run the following command. For more information, see ` [create-log-group](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/logs/create-log-group.html) ` in the AWS CLI v2 Command Reference.
Replace the log group name in the example (`uploadLogsGroup`) with your preferred name.
```
aws logs create-log-group --log-group-name uploadLogsGroup
```
1. To confirm that the log group was created correctly, run the following command.
```
aws logs describe-log-groups --log-group-name-prefix uploadLogsGroup
```
Sample output:
```
{
"logGroups": [
{
"logGroupName": "uploadLogsGroup",
"creationTime": 1674521804657,
"metricFilterCount": 0,
"arn": "arn:aws:logs:us-east-1:111122223333:log-group:uploadLogsGroup:*",
"storedBytes": 0
}
]
}
```
------
## Creating a topic rule
To create an AWS IoT rule, complete the following steps. Choose the appropriate tab depending on whether you prefer to perform the steps through the AWS Management Console or the AWS Command Line Interface (AWS CLI).
------
#### [ AWS Management Console ]
**To create a topic rule by using the AWS Management Console**
1. Open the Rule hub.
1. Open the AWS Management Console and navigate to [AWS IoT](https://console.aws.amazon.com/iot) .
1. On the navigation bar, choose **Message routing** and then **Rules**.
1. Choose **Create rule**.
1. Enter the rule properties.
1. Enter an alphanumeric **Rule name**.
1. (Optional) Enter a **Rule description** and **Tags**.
1. Choose **Next**.
1. Enter a SQL statement.
1. Enter a SQL statement using the MQTT topic that you defined for ingestion.
For example, `SELECT * FROM '$aws/rules/things/thing_name/logs' `
1. Choose **Next**.
1. Enter rule actions.
1. On the **Action 1** menu, choose **CloudWatch logs**.
1. Choose the **Log group name** and then choose the log group that you created.
1. Select **Use batch mode**.
1. Specify the IAM role for the rule.
If you have an IAM role for the rule, do the following.
1. On the **IAM role** menu, choose your IAM role.
If you don't have an IAM role for the rule, do the following.
1. Choose **Create new role**.
1. For **Role name**, enter a unique name and choose **Create**.
1. Confirm that the IAM role name is correct in the **IAM role** field.
1. Choose **Next**.
1. Review the template configuration.
1. Review the settings for the Job template to verify they're correct.
1. When you're done, choose **Create**.
------
#### [ AWS CLI ]
**To create an IAM role and a topic rule by using the AWS CLI**
1. Create an IAM role that grants rights to the AWS IoT rule.
1. Create an IAM policy.
To create an IAM policy, run the following command. Make sure you update the `policy-name` parameter value. For more information, see [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-policy.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-policy.html) in the AWS CLI v2 Command Reference.
**Note**
If you're using a Microsoft Windows operating system, you might need to replace the end of line marker (\$1) with a tick (`) or another character.
```
aws iam create-policy \
--policy-name uploadLogsPolicy \
--policy-document \
'{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"iot:CreateTopicRule",
"iot:Publish",
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:GetLogEvents"
],
"Resource": "*"
}
}'
```
1. Copy the policy ARN from your output into a text editor.
Sample output:
```
{
"Policy": {
"PolicyName": "uploadLogsPolicy",
"PermissionsBoundaryUsageCount": 0,
"CreateDate": "2023-01-23T18:30:10Z",
"AttachmentCount": 0,
"IsAttachable": true,
"PolicyId": "AAABBBCCCDDDEEEFFFGGG",
"DefaultVersionId": "v1",
"Path": "/",
"Arn": "arn:aws:iam::111122223333:policy/uploadLogsPolicy",
"UpdateDate": "2023-01-23T18:30:10Z"
}
}
```
1. Create an IAM role and trust policy.
To create an IAM policy, run the following command. Make sure you update the `role-name` parameter value. For more information, see [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-role.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-role.html) in the AWS CLI v2 Command Reference.
```
aws iam create-role \
--role-name uploadLogsRole \
--assume-role-policy-document \
'{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}'
```
1. Attach the IAM policy to the rule.
To create an IAM policy, run the following command. Make sure you update the `role-name` and `policy-arn` parameter values. For more information, see [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/attach-role-policy.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/attach-role-policy.html) in the AWS CLI v2 Command Reference.
```
aws iam attach-role-policy \
--role-name uploadLogsRole \
--policy-arn arn:aws:iam::111122223333:policy/uploadLogsPolicy
```
1. Review the role.
To confirm that the IAM role was created correctly, run the following command. Make sure you update the `role-name` parameter value. For more information, see [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/get-role.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/get-role.html) in the AWS CLI v2 Command Reference.
```
aws iam get-role --role-name uploadLogsRole
```
Sample output:
```
{
"Role": {
"Path": "/",
"RoleName": "uploadLogsRole",
"RoleId": "AAABBBCCCDDDEEEFFFGGG",
"Arn": "arn:aws:iam::111122223333:role/uploadLogsRole",
"CreateDate": "2023-01-23T19:17:15+00:00",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
},
"Description": "",
"MaxSessionDuration": 3600,
"RoleLastUsed": {}
}
}
```
1. Create an AWS IoT topic rule in the AWS CLI.
1. To create an AWS IoT topic rule, run the following command. Make sure you update the `--rule-name`,`sql` statement, `description`,`roleARN `, and `logGroupName` parameter values. For more information, see [create-topic-rule](https://awscli.amazonaws.com/v2/documentation/api/2.0.34/reference/iot/create-topic-rule.html) in the AWS CLI v2 Command Reference.
```
aws iot create-topic-rule \
--rule-name uploadLogsRule \
--topic-rule-payload \
'{
"sql":"SELECT * FROM 'rules/things/thing_name/logs'",
"description":"Upload logs test rule",
"ruleDisabled":false,
"awsIotSqlVersion":"2016-03-23",
"actions":[
{"cloudwatchLogs":
{"roleArn":"arn:aws:iam::111122223333:role/uploadLogsRole",
"logGroupName":"uploadLogsGroup",
"batchMode":true}
}
]
}'
```
1. To confirm that the rule was created correctly, run the following command. Make sure you update the `role-name` parameter value. For more information, see [get-topic-rule](https://awscli.amazonaws.com/v2/documentation/api/2.0.34/reference/iot/get-topic-rule.html) in the AWS CLI v2 Command Reference.
```
aws iot get-topic-rule --rule-name uploadLogsRule
```
Sample output:
```
{
"ruleArn": "arn:aws:iot:us-east-1:111122223333:rule/uploadLogsRule",
"rule": {
"ruleName": "uploadLogsRule",
"sql": "SELECT * FROM rules/things/thing_name/logs",
"description": "Upload logs test rule",
"createdAt": "2023-01-24T16:28:15+00:00",
"actions": [
{
"cloudwatchLogs": {
"roleArn": "arn:aws:iam::111122223333:role/uploadLogsRole",
"logGroupName": "uploadLogsGroup",
"batchMode": true
}
}
],
"ruleDisabled": false,
"awsIotSqlVersion": "2016-03-23"
}
}
```
------
## Sending device-side logs to AWS IoT
**To send device-side logs to AWS IoT**
1. To send historical logs to AWS IoT, communicate with your devices to ensure the following.
+ The log information is sent to the correct topic namespace as specified within the *Prerequisites* section of this procedure.
For example, `$aws/rules/things/thing_name/logs`
+ The MQTT message payload is formatted correctly. For more information about MQTT topic and recommended naming convention, see the [MQTT topics](upload-device-logs-to-cloudwatch.md#upload-mqtt-topics-overview) section within [Upload device-side logs to Amazon CloudWatch](upload-device-logs-to-cloudwatch.md) .
1. Confirm that the MQTT messages are received within the AWS IoT MQTT client.
1. Open the AWS Management Console and navigate to [AWS IoT](https://console.aws.amazon.com/iot/home).
1. To view the **MQTT test client**, on the navigation bar, choose **Test**,**MQTT test client**.
1. For **Subscribe to a topic**,**Topic filter**, enter the *topic namespace*.
1. Choose **Subscribe**.
MQTT messages appear in the **Subscriptions** and **Topic** table, as seen in the following. These messages can take up to five minutes to appear.
![\[MQTT messages appearing in the Subscriptions and Topic table.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/uploading-logs-rules-start-messages-sample-mqtt.png)
## Viewing the log data
**To review your log records in CloudWatch Logs**
1. Open the AWS Management Console, and navigate to [CloudWatch](https://console.aws.amazon.com/cloudwatch).
1. On the navigation bar, choose **Logs**,**Logs Insights**.
1. On the **Select log group(s)** menu, choose the log group you specified in the AWS IoT rule.
1. On the **Logs insights** page, choose **Run query**.
# Logging AWS IoT API calls using AWS CloudTrail
AWS IoT 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. CloudTrail captures all API calls for AWS IoT as events, including calls from the AWS IoT console and from code calls to the AWS IoT APIs. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for AWS IoT. 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, the IP address from which the request was made, who made the request, when it was made, and other details.
To learn more about CloudTrail, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
## AWS IoT information in CloudTrail
CloudTrail is enabled on your AWS account when you create the account. When activity occurs in AWS IoT, 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, create a trail. A trail enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all AWS Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. You can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see:
+ [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#cloudtrail-aws-service-specific-topics-integrations)
+ [Configuring Amazon SNS Notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.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)
**Note**
AWS IoT data plane actions (device side) are not logged by CloudTrail. Use CloudWatch to monitor these actions.
Generally speaking, AWS IoT control plane actions that make changes are logged by CloudTrail. Calls such as **CreateThing**, **CreateKeysAndCertificate**, and **UpdateCertificate** leave CloudTrail entries, while calls such as **ListThings** and **ListTopicRules** do not.
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 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 actions are documented in the [AWS IoT API Reference](https://docs.aws.amazon.com/iot/latest/apireference/). AWS IoT Wireless actions are documented in the [AWS IoT Wireless API Reference](https://docs.aws.amazon.com/iot-wireless/latest/apireference/welcome.html).
## Understanding AWS IoT log file entries
A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, request parameters, and so on. CloudTrail log files are not an ordered stack trace of the public API calls, so they do not appear in any specific order.
The following example shows a CloudTrail log entry that demonstrates the `AttachPolicy` action.
```
{
"timestamp":"1460159496",
"AdditionalEventData":"",
"Annotation":"",
"ApiVersion":"",
"ErrorCode":"",
"ErrorMessage":"",
"EventID":"8bff4fed-c229-4d2d-8264-4ab28a487505",
"EventName":"AttachPolicy",
"EventTime":"2016-04-08T23:51:36Z",
"EventType":"AwsApiCall",
"ReadOnly":"",
"RecipientAccountList":"",
"RequestID":"d4875df2-fde4-11e5-b829-23bf9b56cbcd",
"RequestParamters":{
"principal":"arn:aws:iot:us-east-1:123456789012:cert/528ce36e8047f6a75ee51ab7beddb4eb268ad41d2ea881a10b67e8e76924d894",
"policyName":"ExamplePolicyForIoT"
},
"Resources":"",
"ResponseElements":"",
"SourceIpAddress":"52.90.213.26",
"UserAgent":"aws-internal/3",
"UserIdentity":{
"type":"AssumedRole",
"principalId":"AKIAI44QH8DHBEXAMPLE",
"arn":"arn:aws:sts::12345678912:assumed-role/iotmonitor-us-east-1-beta-InstanceRole-1C5T1YCYMHPYT/i-35d0a4b6",
"accountId":"222222222222",
"accessKeyId":"access-key-id",
"sessionContext":{
"attributes":{
"mfaAuthenticated":"false",
"creationDate":"Fri Apr 08 23:51:10 UTC 2016"
},
"sessionIssuer":{
"type":"Role",
"principalId":"AKIAI44QH8DHBEXAMPLE",
"arn":"arn:aws:iam::123456789012:role/executionServiceEC2Role/iotmonitor-us-east-1-beta-InstanceRole-1C5T1YCYMHPYT",
"accountId":"222222222222",
"userName":"iotmonitor-us-east-1-InstanceRole-1C5T1YCYMHPYT"
}
},
"invokedBy":{
"serviceAccountId":"111111111111"
}
},
"VpcEndpointId":""
}
```