Configure logging role and policy Configure default logging in the Amazon IoT (console)Configure default logging in Amazon IoT (CLI)Configure resource-specific logging in Amazon IoT (CLI)Log levels

Configure Amazon IoT logging

You must enable logging by using the Amazon IoT console, CLI, or API before you can monitor and log Amazon IoT activity.

You can enable logging for all of Amazon IoT or only specific thing groups. You can configure Amazon IoT logging by using the Amazon IoT console, CLI, or API; however, you must use the CLI or API to configure logging for specific thing groups.

When considering how to configure your Amazon IoT logging, the default logging configuration determines how Amazon IoT activity will be logged unless specified otherwise. Starting out, you might want to obtain detailed logs with a default 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 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 Amazon IoT. For information on device-side logging and monitoring, see Upload device-side logs to CloudWatch.

For information on logging and monitoring Amazon IoT Greengrass, see Logging and monitoring in Amazon IoT Greengrass. As of June 30, 2023, the Amazon IoT Greengrass Core software has migrated to Amazon IoT Greengrass Version 2.

Configure logging role and policy

Before you can enable logging in Amazon IoT, you must create an IAM role and a policy that gives Amazon permission to monitor Amazon IoT activity on your behalf. You can also generate an IAM role with the policies needed in the Logs section of the Amazon IoT console.

Note

Before you enable Amazon IoT logging, make sure 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.

If you expect high traffic patterns in Amazon IoT Core due to load testing, consider turning off IoT logging to prevent throttling. If high traffic is detected, our service may disable logging in your account.

Following shows how to create a logging role and policy for Amazon IoT Core resources.

Create a logging role

To create a logging role, open the Roles hub of the IAM console and choose Create role.

Under Select trusted entity, choose Amazon Service. Then choose IoT under Use case. If you don't see IoT, enter and search IoT from the Use cases for other Amazon services: drop-down menu. Select Next.
On the Add permissions page, you will see the policies that are automatically attached to the service role. Choose Next.
On the Name, review, and create page, enter a Role name and Role description for the role, then choose Create role.
In the list of Roles, find the role you created, open it, and copy the Role ARN (logging-role-arn) to use when you Configure default logging in the Amazon IoT (console).

Logging role policy

The following policy documents provide the role policy and trust policy that allow Amazon IoT to submit log entries to CloudWatch on your behalf. If you also allowed Amazon 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.

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:${partition}:logs:${region}:${accountId}:log-group:AWSIotLogsV2:*"
			]
		}
	]
}

Trust policy to log only Amazon IoT Core activity:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Effect": "Allow",
            "Principal": {
                "Service": "iot.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Configure default logging in the Amazon IoT (console)

This section describes how use the Amazon IoT console to configure logging for all of Amazon IoT. To configure logging for only specific thing groups, you must use the CLI or API. For information about configuring logging for specific thing groups, see Configure resource-specific logging in Amazon IoT (CLI).

To use the Amazon IoT console to configure default logging for all of Amazon IoT

Sign in to the Amazon IoT console. For more information, see Open the Amazon IoT console.
In the left navigation pane, choose Settings. In the Logs section of the Settings page, choose Manage logs.

The Logs page displays the logging role and level of verbosity used by all of Amazon IoT.
On the Logs page, choose Select role to specify a role that you created in Create a logging role, or Create Role to create a new role to use for logging.
Choose the Log level that describes the level of detail of the log entries that you want to appear in the CloudWatch logs.
Choose Update to save your changes.

After you've enabled logging, visit Viewing Amazon IoT logs in the CloudWatch console to learn more about viewing the log entries.

Configure default logging in Amazon IoT (CLI)

This section describes how to configure global logging for Amazon IoT by using the CLI.

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 before continuing.

The principal used to call the API must have Passing role permissions for your logging role.

You can also perform this procedure with the API by using the methods in the Amazon API that correspond to the CLI commands shown here.

To use the CLI to configure default logging for Amazon IoT

Use the set-v2-logging-options command to set the logging options for your account.
```
aws iot set-v2-logging-options \
    --role-arn logging-role-arn \
    --default-log-level log-level
```
where:

--role-arn

The role ARN that grants Amazon IoT permission to write to your logs in CloudWatch Logs.

--default-log-level

The log level to use. Valid values are: ERROR, WARN, INFO, DEBUG, or DISABLED

--no-disable-all-logs

An optional parameter that enables all Amazon IoT logging. Use this parameter to enable logging when it is currently disabled.

--disable-all-logs

An optional parameter that disables all Amazon IoT logging. Use this parameter to disable logging when it is currently enabled.
Use the get-v2-logging-options command to get your current logging options.
```
aws iot get-v2-logging-options
```

After you've enabled logging, visit Viewing Amazon IoT logs in the CloudWatch console to learn more about viewing the log entries.

Note

Amazon 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 to configure your logging options and, when possible, change legacy applications that use the older versions.

Configure resource-specific logging in Amazon IoT (CLI)

This section describes how to configure resource-specific logging for Amazon IoT by using the CLI. Resource-specific logging allows you to specify a logging level for a specific thing group.

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, Amazon 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 Amazon IoT thing to an MQTT client connection.

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 before continuing.

The principal used to call the API must have Passing role permissions for your logging role.

You can also perform this procedure with the API by using the methods in the Amazon API that correspond to the CLI commands shown here.

To use the CLI to configure resource-specific logging for Amazon IoT

Use the set-v2-logging-options command to set the logging options for your account.
```
aws iot set-v2-logging-options \
    --role-arn logging-role-arn \
    --default-log-level log-level
```
where:

--role-arn

The role ARN that grants Amazon IoT permission to write to your logs in CloudWatch Logs.

--default-log-level

The log level to use. Valid values are: ERROR, WARN, INFO, DEBUG, or DISABLED

--no-disable-all-logs

An optional parameter that enables all Amazon IoT logging. Use this parameter to enable logging when it is currently disabled.

--disable-all-logs

An optional parameter that disables all Amazon IoT logging. Use this parameter to disable logging when it is currently enabled.
Use the set-v2-logging-level command to configure resource-specific logging for a thing group.
```
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 target_type value must be one of: THING_GROUP | CLIENT_ID | SOURCE_IP | 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.
```
aws iot set-v2-logging-level \ 
              --log-target targetType=CLIENT_ID,targetName=ClientId1 \
              --log-level DEBUG
```
Use the list-v2-logging-levels command to list the currently configured logging levels.
```
aws iot list-v2-logging-levels
```
Use the delete-v2-logging-level 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
```
--targetType

The target_type value must be one of: THING_GROUP | CLIENT_ID | SOURCE_IP | PRINCIPAL_ID.

--targetName

The name of the thing group for which to remove the logging level.

After you've enabled logging, visit Viewing Amazon IoT logs in the CloudWatch console to learn more about viewing the log entries.

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.

Logs include ERROR information only.

WARN

Anything that can potentially cause inconsistencies in the system, but might not cause the operation to fail.

Logs include ERROR and WARN information.

INFO

High-level information about the flow of things.

Logs include INFO, ERROR, and WARN information.

DEBUG

Information that might be helpful when debugging a problem.

Logs include DEBUG, INFO, ERROR, and WARN information.

DISABLED

All logging is disabled.

Javascript is disabled or is unavailable in your browser.

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

Monitor Amazon IoT

Monitor Amazon IoT alarms and metrics using Amazon CloudWatch