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 Primer 查看调试页面。在本部分中，我们将介绍用于调试调试问题的工具和技术。
使用 Google Home Analytics
我们创建了一组指标，以便您通过跟踪事件并了解错误可能会出现的阶段，从而调查调试问题。如上一部分所述，你可以在 Matter 集成信息中心内找到这些信息。
此信息中心内的图表提供了有关设备调试的数据：
“设备数量”图表会显示指定日期用户尝试调试的次数。成功率会显示在 Google 端这些事件的感知成功率。每次调试尝试都会生成一组关联状态的事件。在上述任一状态下发生错误时，系统也会将其捕获到错误细分图表中。
调试状态：
- COMMISSIONING_STARTED
- ONBOARDING_PAYLOAD_GENERATED
- LOCAL_DISCOVERY_SUCCESSFUL
- PASE_CONNECTION_SUCCESSFUL
- NOC_ADDED_SUCCESSFULLY
- COMMISSIONING_COMPLETE
如需查看这些事件的详细版本，请前往操作 >日志记录 >日志浏览器。如需过滤佣金错误，您可以搜索“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 调试的警告消息，询问您是否允许计算机访问手机中的信息：
- 如果您收到此警告消息，请点击允许。
- 使用以下命令，从终端发出 list devices 命令，检查您的计算机是否可以通过 ADB 访问手机：
$ adb devices
这应该会返回类似于以下内容的响应：
List of devices attached <phone-id> device
您的 <phone-id>是一个字母数字字符串，用于唯一标识您的设备。
- 请记住
<phone-id>值，以便在后续步骤中使用。
收集系统信息
接下来，查看设备上的应用和系统的版本信息。
- 如需查看 Android OS 版本，请执行以下操作：
$ 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 服务提供主屏幕 / 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 Hubs 捕获的错误，这些数据说明了设备控制尝试失败的原因。
使用日志
每个 Matter 设备控制问题也会在系统中生成错误日志。您可以通过搜索“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 集成。希望你有时间构建 Matter 与 Google Home 的集成。
后续步骤
请尝试进行以下练习并探索其他资源：