本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 設定 AWS IoT 記錄 您必須使用 AWS IoT 主控台、CLI 或 API 啟用記錄，才能監控和記錄 AWS IoT 活動。您可以在 AWS IoT 三個層級設定 的記錄：帳戶層級、事件層級或資源特定層級。事件層級和資源特定的記錄僅適用於 V2 記錄。使用 V1 記錄的客戶必須執行 V2 遷移，才能存取這些功能。請參閱[詳細資訊](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#migration-v1-v2)。 考慮如何設定 AWS IoT 記錄時，帳戶層級記錄組態會決定記錄 AWS IoT 活動的方式，除非另有指定。從一開始，您可能想要取得預設日誌[層級為 INFO 或 DEBUG 的詳細日誌](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#log-level)。檢閱初始日誌之後，您可以將預設日誌層級變更為較不詳細的層級，例如帳戶或事件層級的 WARN 或 ERROR，並針對可能需要更多關注的資源設定更詳細的資源特定日誌層級。您可以隨時更改日誌層級。 本主題涵蓋雲端登入 AWS IoT。如需裝置端日誌和監控的相關資訊，請參閱[將裝置端日誌上傳至 CloudWatch](https://docs.aws.amazon.com/iot/latest/developerguide/upload-device-logs-to-cloudwatch.html)。 如需記錄和監控的資訊 AWS IoT Greengrass，請參閱 [中的記錄和監控 AWS IoT Greengrass](https://docs.aws.amazon.com/greengrass/v2/developerguide/logging-and-monitoring.html)。 ## 設定 V2 登入 AWS IoT ### 判斷您的記錄版本 如果未啟用 V2[GetV2LoggingOptions API](https://docs.aws.amazon.com/iot/latest/apireference/API_GetV2LoggingOptions.html) 會傳回 NotConfiguredException。當 V1 記錄正在使用，或未設定記錄時，就會發生此錯誤。 ### 了解 V2 記錄功能 V2 記錄提供兩個關鍵功能：事件層級記錄和資源特定的記錄。事件層級記錄可透過可自訂的日誌層級和 CloudWatch 日誌群組目的地來啟用目標記錄組態。資源特定的記錄可讓您依物件群組、來源 IP、用戶端 ID 或主體 ID 篩選日誌。這些功能共同提供 IoT 操作的精細控制和全面可見性，透過消除不必要的記錄活動來改善日誌可搜尋性並降低成本。 ### 從 V1 移轉至 V2 您可以透過 AWS [CLI](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/set-v2-logging-options.html) 或 SDK，使用 SetV2LoggingOptions API 遷移至 V2 記錄。 SetV2LoggingOptions 遷移後， AWS IoT 會自動將所有日誌路由到 CloudWatch 日誌群組 'AWSIotLogsV2'。重要：如果您的下游應用程式或資源使用來自「AWSIotLogs」的資訊，請更新它們以使用對應的日誌群組路徑。 ## 設定記錄角色和政策 在啟用登入之前 AWS IoT，您必須建立 IAM 角色和政策，以授予代表您將 AWS IoT 日誌活動寫入 CloudWatch 日誌群組的 AWS IoT 許可。您也可以使用[AWS IoT 主控台的日誌區段](https://console.aws.amazon.com/iot/home#/settings/logging)中所需的政策來產生 IAM 角色。 **注意** 啟用 AWS IoT 記錄之前，請確定您了解 CloudWatch Logs 存取許可。具有 CloudWatch Logs 存取權限的使用者可從您的裝置查看除錯資訊。如需更多資訊，請參閱 [Amazon CloudWatch Logs 的驗證與存取控制](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/auth-and-access-control-cw.html)。 如果您 AWS IoT Core 預期 因為負載測試而有高流量模式，請考慮停用 IoT 記錄，以防止限流。若偵測到高流量，我們的服務可能會停用您的帳戶登入。 以下說明如何為 AWS IoT Core 資源建立記錄角色和政策。 ### 建立記錄角色 若要建立記錄角色，請開啟 [IAM 主控台的角色中樞](https://console.aws.amazon.com/iam/home#/roles)，然後選擇 **Create role** (建立角色)。 1. 在 **Select trusted entity** (選取信任的實體) 下，選取 **AWS service** (服務)。然後在 **Use case** (使用案例) 下選擇 **IoT**。如果未顯示 **IoT**，請從 Use cases for other AWS services: (其他 服務的使用案例：) 下拉式清單中輸入並搜尋 **IoT**。選取**下一步**。 1. 在 **Add permissions** (新增許可) 頁面上，您會看到自動連接到服務角色的政策。選擇**下一步**。 1. 在 **Name, review, and create** (命名、檢閱和建立) 頁面上，輸入角色的 **Role name** (角色名稱) 和 **Role description** (角色描述)，然後選擇 **Create role** (建立角色)。 ### 記錄角色政策 下列政策文件提供了角色政策及信任政策，用以允許 AWS IoT 代表您提交日誌項目至 CloudWatch。如果您使用自訂 CloudWatch 日誌群組設定事件層級記錄，則必須更新角色政策以包含自訂資源 ARN。 如果您也允許 AWS IoT Core for LoRaWAN 提交日誌項目，您會看到為您建立的政策文件，可記錄這兩個活動。 **注意** 這些文件是在您建立記錄角色時為您建立的。文件具有變數 * `${partition}`、 * * `${region}` *和 * `${accountId}` *，您必須將其取代為值。 將分割區取代為區域的分割區。 將區域取代為您使用 AWS 的區域。請確定您使用與在裝置上設定 CLI AWS 相同的 AWS 區域。 將 account-id 取代為 AWS 您的帳戶 ID。 角色政策： **** ``` { "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:*" ] } ] } ``` 僅記錄 AWS IoT Core 活動的信任政策： **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` AWS IoT 由於 IAM 角色許可不足，記錄可能無法發佈記錄到 CloudWatch Logs。發生這種情況時，請檢查 [ CloudWatch 記錄指標](https://docs.aws.amazon.com/iot/latest/developerguide/metrics_dimensions.html#logging-metrics)以調查故障並進行疑難排解。 ## 在 AWS IoT （主控台） 中設定記錄 本節說明如何使用 AWS IoT 主控台設定 AWS IoT 記錄。您可以設定帳戶層級、事件層級和資源特定的記錄。 **若要設定 AWS IoT 記錄：** 1. 登入 AWS IoT 主控台。如需詳細資訊，請參閱[開啟 AWS IoT 主控台](setting-up.md#iot-console-signin)。 1. 在左側導覽窗格中，選擇**日誌 **（先前是設定下的區段）。 1. 設定帳戶層級記錄：帳戶層級記錄會套用至所有 AWS IoT 機群 （裝置或端點），除非被事件層級或資源特定設定覆寫。 1. 在帳戶層級記錄下，選取**管理帳戶層級記錄**以進行更新。 1. 選取「啟用記錄」核取方塊，開始將日誌傳送至 CloudWatch。取消勾選「啟用記錄」時， AWS IoT 不會將任何日誌傳送至 CloudWatch 日誌群組，無論事件層級或資源層級記錄組態為何。 1. 在 **IAM 日誌角色**下，從下拉式清單中選取現有角色。您可以**檢視角色詳細資訊**來檢查角色許可。或者，選取**建立新角色**以設定新的 IAM 角色。記錄角色提供允許 代表您 AWS IoT 將日誌項目提交至 CloudWatch 的政策。如果您使用自訂 CloudWatch 日誌群組設定事件層級記錄，則必須更新角色政策，以包含此日誌群組的 ARN。 1. 選擇對應至您要顯示在 CloudWatch Logs 中日誌項目[詳細資訊層級](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#log-level)**的預設**日誌層級。注意：日誌層級「DEBUG」提供最詳細的資訊，但會增加 CloudWatch 成本。無法在帳戶層級設定 CloudWatch 日誌群組目的地。不過，您可以為個別事件類型指定自訂日誌群組，如下節所述。 1. 選擇**更新記錄**以儲存您的變更。 1. 事件層級記錄可讓您選擇性地擷取相關事件的日誌，並將其導向至專用的 CloudWatch 日誌群組。這可讓您靈活地依使用案例組織日誌，以獲得更佳的可探索性、與不同的對象共用日誌，以及啟用日誌並根據事件重要性設定日誌層級，以降低 CloudWatch 成本。 設定**事件層級記錄**：事件層級記錄會擷取特定 AWS IoT 事件，例如用戶端身分驗證嘗試。這些設定會覆寫帳戶層級記錄。 1. 在**事件層級記錄**區段下，選取**管理事件層級記錄**以進行更新。 1. 根據預設，事件類型會繼承帳戶層級的記錄組態。注意：設定資源特定的記錄時，它會覆寫帳戶和事件層級設定。 1. 若要修改個別事件的設定，請按一下對應事件列中的值。您可以同時調整日誌層級和 CloudWatch 日誌群組目的地。指定自訂 CloudWatch 日誌群組目的地時，您必須驗證 IAM 角色政策是否包含新日誌群組的許可。未更新角色政策將 AWS IoT 阻止 將日誌寫入自訂日誌群組。進行選擇後，請按一下核取記號以確認您的選擇。**「已修改」**欄會顯示「是」，指出待定的變更。 1. 按一下**更新記錄**以套用您的變更，或選擇**取消**以捨棄。 1. 設定資源特定覆寫：資源特定覆寫會將記錄設定套用至選取的資源。資源可以是物件群組、來源 IP、用戶端 ID 或主體 ID。資源特定的記錄組態會覆寫帳戶層級和事件層級設定。啟用時，它會在指定資源的已設定記錄層級產生所有事件類型的日誌。例如，您可以為特定物件設定偵錯層級記錄，同時保留所有其他物件的資訊層級記錄。 1. 在**資源特定覆寫區段中選取新增**資源特定覆寫。 1. 選擇日誌目標：物件群組、來源 IP、用戶端 ID 或主體 ID。 1. 輸入所選目標類型的對應日誌目標值。 1. 從資源特定日誌層級區段的下拉式功能表中選取所需的日誌層級。 1. 按一下**提交**以新增覆寫，或按一下**取消**以捨棄變更。 1. 若要修改現有的資源特定覆寫，請選取資源旁的核取方塊，然後按一下「移除」來刪除覆寫，或按一下「編輯」來修改。 啟用記錄之後，請造訪 [在 CloudWatch 主控台中檢視 AWS IoT 日誌](cloud-watch-logs.md#viewing-logs) 以進一步了解檢視記錄項目。 ## 在 AWS IoT (CLI) 中設定帳戶和事件層級登入 本節說明如何使用 AWS IoT CLI 設定 的全域記錄。 您可以選擇性地設定事件層級記錄。事件層級記錄會在事件層級擷取記錄資訊，例如身分驗證和授權或憑證建立事件。您可以在事件層級自訂日誌層級和 CloudWatch 日誌群組目的地。相較於帳戶層級記錄，事件層級記錄在更目標層級運作，因此會覆寫帳戶層級記錄設定。這種階層式方法可讓您根據不同類型的事件的操作重要性和成本考量來維護不同的記錄策略。 **注意** 您需要您想要使用的角色的 Amazon Resource Name (ARN)。如果您需要建立用於記錄的角色，請在繼續前參閱 [建立記錄角色](#create-logging-role)。為任何事件類型指定自訂 CloudWatch 日誌群組時，請確定您的記錄角色具有目標日誌群組的必要許可。 用於進行 API 呼叫的委託人必須擁有您記錄角色的 [傳遞角色許可](pass-role.md)。 您也可以使用 API 中對應至此處所示 CLI 命令的方法來使用 AWS API 執行此程序。 **使用 CLI 設定 的預設記錄 AWS IoT** 1. 請使用 [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) 命令來設定您的帳戶的記錄選項。 ``` aws iot set-v2-logging-options \ --event-configurations event-configuration-list \ --role-arn logging-role-arn \ --default-log-level log-level ``` 其中： **--role-arn** 角色 ARN，授予在 CloudWatch Logs 中寫入日誌的 AWS IoT 許可。初始設定需要 Role-arn 組態。 **--default-log-level** 欲使用的[日誌層級](#log-level)。有效值為：`ERROR`、`WARN`、`DEBUG`、 `INFO`或 `DISABLED`。初始設定需要Default-log-level組態。 **--no-disable-all-logs** 啟用所有 AWS IoT 記錄的選用參數。使用此參數可在目前該參數停用時啟用記錄功能。 **--disable-all-logs** 選用參數，可停用所有 AWS IoT 記錄。使用此參數可在該參數目前啟用時停用記錄功能。 **--event-configurations** 此參數是選用的，可讓您自訂個別事件類型的記錄設定： + eventType：覆寫帳戶層級設定的事件類型 + logLevel：使用 DEBUG、INFO、 ERROR、WARN 或 DISABLED 覆寫帳戶層級設定 + logDestination：指定用於日誌交付的自訂 CloudWatch 日誌群組 您可以為每個事件類型分別設定記錄層級和日誌目的地。如果未指定，事件會繼承帳戶層級設定 ``` aws iot set-v2-logging-options \ --event-configurations "[{\"eventType\":\"Publish-In\",\"logLevel\":\"INFO\",\"logDestination\":\"examplePublishInLogGroup\"}]" ``` 1. 使用 [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) 命令取得目前的記錄選項。 ``` aws iot get-v2-logging-options \ --verbose ``` 其中： **--verbose** 選用參數，可讓您擷取所有 eventTypes 及其組態。 啟用記錄之後，請造訪 [在 CloudWatch 主控台中檢視 AWS IoT 日誌](cloud-watch-logs.md#viewing-logs) 以進一步了解檢視記錄項目。 **注意** AWS IoT 繼續支援較舊的命令 (**set-logging-options** 和 **get-logging-options**) 來設定和取得您帳戶的全域記錄。請注意，這些指令在使用時所產生的記錄包含純文字，而非 JSON 有效承載，且記錄延遲通常會更高。這些較舊指令的實施將不會進一步改進。我們建議您使用[「v2」版本](https://docs.aws.amazon.com/iot/latest/developerguide/configure-logging.html#migration-v1-v2)來設定記錄選項，並盡可能變更使用舊版的舊版應用程式。 ## 在 AWS IoT (CLI) 中設定資源特定覆寫 本節說明如何 AWS IoT 使用 CLI 設定 的資源特定覆寫。資源特定覆寫可讓您為物件群組、用戶端 ID、來源 IP 或主體 ID 識別的特定資源指定記錄層級。啟用資源特定記錄時，它會覆寫帳戶層級和事件層級設定。所有事件類型都會在設定的日誌層級為指定的資源產生日誌，即使這些事件在事件層級組態中已停用。 物件群組可以包含其他物件群組來建立階層關係。此程序說明如何設定單一物件群組的記錄。您可以將此程序套用至階層中的父項物件群組，以設定階層中所有物件群組的記錄。您也可以將此過程應用於子事件組，以覆蓋其父項的記錄組態。 物件可以是物件群組的成員。此成員資格允許物件繼承套用至物件群組的組態、政策和設定。物件群組用於管理和套用設定到多個物件，而不是個別處理每個物件。當您的用戶端 ID 符合物件名稱時， AWS IoT Core 會自動將用戶端工作階段與對應的物件資源建立關聯。這可讓用戶端工作階段繼承套用至物件所屬物件群組的組態和設定，包括記錄層級。如果您的用戶端 ID 與物件名稱不相符，您可以啟用獨佔物件附件來建立關聯。如需詳細資訊，請參閱 [將 AWS IoT 物件與 MQTT 用戶端連線建立關聯](exclusive-thing.md)。 除物件群組之外，您還可以記錄目標，如裝置的用戶端 ID、來源 IP 和主體 ID。 **注意** 您需要您想要使用的角色的 Amazon Resource Name (ARN)。如果您需要建立用於記錄的角色，請在繼續前參閱 [建立記錄角色](#create-logging-role)。 用於進行 API 呼叫的委託人必須擁有您記錄角色的 [傳遞角色許可](pass-role.md)。 您也可以使用 API 中對應至此處所示 CLI 命令的方法來使用 AWS API 執行此程序。 **使用 CLI 設定 的資源特定覆寫 AWS IoT** 1. 使用下列命令設定資源特定記錄之前，請先啟用帳戶層級記錄：aws iot set-v2-logging-options 命令 1. 使用 [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)命令來設定資源特定的覆寫。如需物件群組組態，請參閱下列範例： ``` aws iot set-v2-logging-level \ --log-target targetType=THING_GROUP,targetName=thing_group_name \ --log-level log_level ``` **--log-target** 您設定欲記錄的資源類型與名稱。`targetType` 值必須是以下其中之一：`THING_GROUP` \$1 `CLIENT_ID` \$1 `SOURCE_IP` \$1 `PRINCIPAL_ID`。log-target 參數值可以是文字，如前面的命令範例所示，也可以是 JSON 字串，例如下列範例。 ``` aws iot set-v2-logging-level \ --log-target '{"targetType": "THING_GROUP","targetName": "thing_group_name"}' \ --log-level log_level ``` **--log-level** 為指定資源產生日誌時所用的日誌層級。有效值為：**DEBUG**、**INFO**、**ERROR**、**WARN** 和 **DISABLED**。 1. 使用 [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) 命令列出目前設定的日誌層級。 ``` aws iot list-v2-logging-levels ``` 1. 使用 [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) 命令可刪除特定資源的日誌層級，如下列範例所示： ``` 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** `target-type` 值必須是以下其中之一：`THING_GROUP` \$1 `CLIENT_ID` \$1 `SOURCE_IP` \$1 `PRINCIPAL_ID`。 **--target-name** 要移除日誌層級之物件群組的名稱。 ## 日誌層級 這些日誌層級會決定記錄的事件，並套用至預設和資源特定的日誌層級。 ERROR 導致操作失敗的錯誤。 範例：由於憑證過期而無法驗證裝置。 日誌內僅含 ERROR 資訊。 WARN 會導致系統內出現不一致，但可能不會造成操作失敗的情況。 範例：接近訊息速率限制。 日誌內僅含 ERROR 和 WARN 資訊。 INFO 物件流的高層級資訊。 範例：用戶端已成功訂閱 MQTT 主題。 日誌包含 INFO、ERROR、WARN 資訊。 DEBUG 可能有助於偵錯問題的資訊。 範例：IoT 規則引擎偵測到發佈至規則主題「規則/測試」的訊息，並成功開始執行。規則是使用 RepublishAction 設定。 日誌包含 DEBUG、INFO、ERROR、WARN 資訊。 DISABLED 已停用所有記錄功能。