1. 准备工作
Matter 可为最终用户提供顺畅的跨平台设备设置和控制体验。这主要是因为多个生态系统组件在幕后协同工作。对于新开发者来说，此类问题排查系统往往令人生畏，因此我们开发了一系列工具和技术，让您在 Google Home 上开发 Matter 设备时更加轻松。
本 Codelab 介绍了 Matter 的三个主要组件。对于上述每种系统，Google 都会提供一组从手机和 Hub 收集的开发者问题排查分析数据：
作为开发者，您必须能够缓解在整个设备开发周期中遇到的问题。项目发布后，您需要以汇总方式监控实际应用中的设备的问题趋势，并通过软件更新来修复这些问题。本 Codelab 将介绍可用于实现这两种目的的方法。
前提条件
- 完成使用 Matter 入门指南，其中包含可正常运行的 Matter 项目和设备设置
- 拥有可连接到工作站的 Android 手机（用于 ADB 日志）
学习内容
- 如何使用智能家居分析工具大规模监控 Matter 问题。
- 如何通过访问错误日志和收集信息来对错误进行问题排查。
- 如何访问 Matter 文档和支持资源以寻求帮助。
2. 查看 Google Home Analytics
监控性能对于成功集成到 Google Home 生态系统至关重要。我们为 Google Cloud Platform 上的智能家居开发者提供了一套监控工具。您可以使用这些工具来衡量项目的效果。
访问项目指标
- 如需访问数据，首先要查看 Google Home 信息中心，方法是登录 Google Cloud 控制台，然后依次前往运维 > 监控 > 信息中心。
您的项目可以使用多个信息中心（包括其他 GCP 产品的信息中心）。为智能家居提供的这些信息中心带有“Google Home Analytics”前缀。
我们目前提供涵盖整个项目的一般信息中心，以及针对特定集成（云端、本地、Matter）或设备类型（摄像头）的信息中心。只有在您集成相应类型的服务，并且项目能够正常运行并满足请求时，这些信息中心才会包含数据。
打开其中一个信息中心后，您会看到一系列如下图所示的图表：
Google Home 信息中心包含各种图表，其中显示了与项目关联的活动的详细信息。在每个集成信息中心内，您都会看到一个图表，其中显示了项目处理的请求总数；一个图表，其中显示了相应集成类型的成功率；以及多个图表，其中显示了涉及的设备类型和特征。此外，借助 Matter，您可以获得一组图表，用于跟踪调试成功率以及设备上的更新推出情况。
请注意，您在 Google Home Analytics 信息中心内看到的包含图表的默认视图只是我们使用智能家居指标数据为您的项目创建的视图。您还可以使用 Metrics Explorer 基于相同的底层指标创建自己的图表，并将其保存到自定义信息中心。
访问错误日志
Logs Explorer 是一组用于处理项目上生成的事件日志的工具。您可以在 Google Cloud 控制台中访问日志浏览器，方法是依次前往运维 > 日志记录 > 日志浏览器。
打开 Logs Explorer 后，您会看到如下所示的视图：
探索器窗口包含各种用于查看、过滤、查询和分析日志的工具。默认情况下，此视图会显示项目可用的所有系统生成的日志，包括在智能家居之外生成的日志。因此，关键在于通过过滤来查找要调试的事件，从而使用这些日志。我们将在调试部分中详细介绍这一点。
3. 调试调试问题
我们将介绍的第一种指标与 Matter 调试事件有关。调试是指用户首次设置 Matter 设备所需的一组步骤。
在设备调试期间，Matter 设备、Google Home 应用和 Matter 网络之间会发生一系列互动。下图展示了其中一些事件：
您可以查看 Matter 启动指南中的调试页面，详细了解每个步骤。在本部分中，我们将介绍用于调试调试问题的工具和技术。
使用 Google Home Analytics
我们创建了一组指标，供您通过跟踪事件并了解错误可能发生在哪个阶段来调查佣金问题。如上一部分所述，您可以在 Matter 集成信息中心内找到这些信息。
此信息中心内的图表提供有关设备调试的数据：
“设备数量”图表显示了用户在指定日期尝试调试的次数。成功率显示的是 Google 端对这些事件的感知成功率。每次调试尝试都会生成一组具有关联状态的事件。如果在上述任何状态下发生错误，系统也会在错误细分图表中捕获该错误。
调试状态：
- COMMISSIONING_STARTED
- ONBOARDING_PAYLOAD_GENERATED
- LOCAL_DISCOVERY_SUCCESSFUL
- PASE_CONNECTION_SUCCESSFUL
- NOC_ADDED_SUCCESSFULLY
- COMMISSIONING_COMPLETE
如需查看这些事件的详细版本，请依次前往运维 > Logging > 日志浏览器。如需过滤调试错误，您可以在查询字段中搜索“clientUpdateLog”和“severity>=ERROR”。
Matter 的调试错误日志如下所示：
{
"insertId": "1a32ry0f6xpzzn",
"jsonPayload": {
"clientUpdateLog": {
"MatterUpdate": {
"reportedProductId": 55,
"sessionId": "1584879052892229997",
"reportedVendorId": 4800,
"commissioningState": "GENERIC_COMMISSIONING_ERROR",
"status": "GENERIC_ERROR"
}
}
},
"resource": {
"type": "assistant_action_project",
"labels": {
"project_id": "<project-id>"
}
},
"timestamp": "2023-03-01T07:09:55.216425297Z",
"severity": "ERROR",
"logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
"receiveTimestamp": "2023-03-01T07:09:55.216425297Z"
}
除了调试状态和状态代码之外，错误日志还包含捕获到的错误的时间戳，以及 Matter 产品 ID，可让您确定是哪个产品导致了错误。从同一调试尝试中生成的一组日志共用一个 sessionId。
通过使用 Google Home Analytics 中的指标，您可以初步了解问题可能发生在哪个阶段。如需查找设备调试错误的根本原因，有时您可能需要使用调试过程中所用移动设备生成的日志进行额外的调试。对于这些操作，您需要使用 Android 调试桥。
使用 Android 调试桥 (ADB)
排查调试问题的另一种方法是使用 Android 调试桥 (ADB) 命令行工具。由于调试主要在移动设备和 Matter 设备之间进行，因此可以使用 ADB 工具访问 Google Home 应用在整个调试过程中生成的日志。
安装平台工具
ADB 随 Android SDK 平台工具一起提供，可通过 Android Studio 或 sdkmanager 命令行工具进行安装。
成功在系统上安装平台工具后，请在终端中使用以下命令检查版本号，以验证 ADB：
$ adb -- version
这应该会显示已安装的 ADB 实用程序的版本号，且不会出现任何错误。
启用 USB 调试
接下来，在 Android 设备上启用 USB 调试。
首先，按照相关步骤在设备上启用开发者选项，然后启用 USB 调试。
这样，ADB 就可以访问设备上当前运行的应用生成的日志。
检索设备 ID
- 使用以下命令运行 ADB 服务器：
$ adb start-server
- 将手机连接到运行 ADB 服务器的计算机。
您可能会在手机上收到有关 USB 调试的警告消息，询问您是否要允许计算机访问手机中的信息：
- 如果您收到此警告消息，请点击允许。
- 在终端中发出列出设备命令，以查看您的计算机是否可以通过 ADB 访问手机，使用以下命令：
$ adb devices
这应该会得到类似如下的回答：
List of devices attached <phone-id> device
<phone-id> 是一个字母数字字符串，用于唯一标识您的设备。
- 请记下
<phone-id>值，以便在后续步骤中使用。
收集系统信息
接下来，检查设备上应用和系统的版本信息。
- 如需查看 Android 操作系统版本，请执行以下操作：
$ adb -s <phone-id> shell getprop ro.build.version.release
- 如需查看 Google Home 应用版本，请执行以下操作：
$ adb -s <phone-id> shell dumpsys package com.google.android.apps.chromecast.app | grep versionName
- 如需检查 Google Play 服务的版本，请执行以下操作：
$ adb -s <phone-id> shell dumpsys package com.google.android.gms | grep "versionName"
- 如需通过 Play 服务检查您是否拥有 Home / Matter 控制模块，请执行以下操作：
$ adb -s <phone-id> shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home"
确保这些返回值受我们生态系统的支持。在就调试失败问题寻求支持时，请务必在支持服务工单中提供系统信息。
收集错误日志
接下来，启动日志收集流程，然后完成调试步骤，以生成要调试的错误事件。
- 运行以下命令，提供您的
<phone-id>以及用于在计算机中保存日志的<file-name>（例如debug_file.txt）。
$ adb -s <phone-id> logcat > <file-name>
这会立即开始记录日志。如果具有所提供名称的文件尚不存在，系统会创建该文件，并在每次发生事件后将手机中的日志添加到该文件中。
继续执行 Matter 设备的调试步骤。
- 找到要调试的错误后，在正在运行的终端窗口中按
Control+C停止日志记录。
您的日志现在应存储在 <file-name> 日志文件中。由于此进程会记录设备中跟踪的每个正在运行的进程的日志，因此该文件中将包含大量日志。因此，您应始终通过搜索所需的条目来利用这些日志。
分析错误日志
调试流程通过 GHA 内名为 MatterCommissioner 的子系统处理。
- 按照分析调试错误时使用的主要策略，使用以下命令查找 MatterCommissioner 子系统生成的错误：
$ grep "MatterCommissioner" <file-name>
这会生成一个包含调试过程中的事件的输出。
- 如果 Matter 设备使用 Thread，您还可以通过以下命令查找 Thread 子系统生成的错误：
$ grep -E "(ThreadNetworkManager|BorderAgentScannerImpl|ThreadBrSynchronizer)" <file-name>
在分析由 ADB 调试过程生成的日志文件时，您还要查找某些模式。许多调试错误会在其错误消息中包含“commissioning failure”字符串。
- 使用以下命令搜索调试失败消息：
$ grep "SetupDevice" $phonelog | grep -A 20 "Commissioning failed"
4. 调试设备控制问题
用户将 Matter 设备设置并纳入 Google Home 生态系统后，即可通过 Google 助理使用语音指令（例如，“Ok Google，打开客厅的灯”）或通过 Home 应用或 Google Nest 显示屏设备上的界面来发出指令。
由于终端设备和 Google Hub 之间的控制规范由 Matter 协调，因此预计设备控制方面的错误会更少。无论如何，我们都会提供指标和日志，以便您调试此类问题。
使用指标
在 Matter 集成信息中心内，您会看到有关设备控制的多个指标。有三种图表对于评估现场设备的性能至关重要：
在控制问题期间，您通常会看到成功百分比呈下降趋势，而错误细分图表呈上升趋势。错误细分图会显示 Google Nest Hub 捕获的有关设备控制尝试失败原因的错误。
使用日志
每个 Matter 设备控制问题也会在系统中生成错误日志。您可以在 Logs Explorer 中搜索“executionLog”来过滤掉这些错误。
Matter 设备控制错误日志如下所示：
{
"insertId": "1a32ry0f6xpzzn",
"jsonPayload": {
"executionLog": {
"executionResults": [
{
"executionType": "MATTER",
"latencyMsec": "6000",
"actionResults": [
{
"action": {
"actionType": "ONOFF_OFF",
"trait": "TRAIT_ON_OFF"
},
"status": {
"externalDebugString": "No message was received before the deadline.",
"statusType": "RESPONSE_TIMEOUT",
"fallbackToCloud": false,
"isSuccess": false
},
"device": {
"deviceType": "OUTLET"
}
}
],
"requestId": "1487232799486580805"
}
]
},
"locale": "en-US"
},
"resource": {
"type": "assistant_action_project",
"labels": {
"project_id": "<project-id>"
}
},
"timestamp": "2023-03-01T15:47:27.311673018Z",
"severity": "ERROR",
"logName": "projects/<project-id>/logs/assistant_smarthome%2Fassistant_smarthome_logs",
"receiveTimestamp": "2023-03-01T15:47:27.311673018Z"
}
每个错误日志都包含时间戳、设备类型和特征，以及 statusType 中与控制请求关联的错误。许多控制错误还包含 externalDebugString，这是一条简短的错误消息，用于说明错误的内容。
5. 调试其他功能
到目前为止，您已经了解了如何处理 Matter 的设备调试和控制问题。生态系统中还有其他功能或推荐的技术可用于确保集成质量。
跟踪 OTA 更新
为了跟踪 Google Home 针对 Matter 设备发布的无线下载 (OTA) 更新，我们提供了一组指标，用于显示现场设备的硬件和软件版本。
在控制台中发布更新后，请密切关注以下指标：
您会看到，在发布后的几天内，越来越多的现场设备会获得与您的 OTA 软件版本相关联的新软件版本。
6. 寻求支持
Google 提供了相关工具和文档，可帮助您调试 Matter 问题，但由于 Matter 生态系统是新推出的，因此这些资源无法涵盖所有问题。在这些情况下，您可以随时与我们或社区联系，寻求支持。
访问开发者渠道
Google 内有三个受到积极监控的开发者渠道：
虽然这些渠道都由同一团队定期监控，但使用哪个渠道存在一些关键差异。
- Stack Overflow：您可以向我们和智能家居开发者社区咨询实现方面的问题或寻求指导。此渠道最适合询问如何排查问题或实现特定功能。
- 问题跟踪器：这是由 Google 官方运行的问题跟踪器系统，外部受众群体可以在其中报告生态系统中的错误。它提供了一些网页工具，可在需要时附加文件和分享敏感信息。使用问题跟踪器是报告生态系统问题或分享功能请求的最佳方式。
- 开发者论坛：如需寻求 Google 官方支持和社区专家的指导，您可以通过 Nest 开发者论坛联系我们。此论坛最适合获取官方开发指南。
订阅开发者简报
除了访问开发者渠道来提出问题之外，我们还会发布季度简报，其中重点介绍新功能，并提供有关 Google 智能家居生态系统状态的新闻。
您可以使用注册表单订阅开发者简报。
7. 恭喜
恭喜！您已成功学习如何使用我们推荐的工具和技巧调试 Matter 集成。祝您在构建可与 Google Home 搭配使用的 Matter 集成时一切顺利。
后续步骤
尝试做以下练习并浏览其他资源：