1. 准备工作
Matter 为最终用户提供顺畅的跨平台设备设置和控制体验。这主要得益于多个生态系统组件在后台协同工作。对新手开发者来说，排查此类系统的问题通常会令人望而却步，因此我们开发了一系列工具和技术，让您作为 Matter 开发者能够更轻松地使用 Google Home。
本 Codelab 介绍了 Matter 的三个主要组件。对于上述每种系统，Google 都会为开发者提供一组从手机和集线器收集的问题排查分析：
作为开发者，您必须能够在整个设备开发周期中减少遇到的问题。项目发布后，您需要汇总地监控实际使用中的设备的问题趋势，并通过软件更新来解决这些问题。本 Codelab 介绍了可用于实现这两种目的的技术。
前提条件
- 完成 Matter 使用入门指南，并创建可用的 Matter 项目和设备设置
- 拥有可连接到工作站的 Android 手机（用于 ADB 日志）
学习内容
- 如何使用智能家居分析工具大规模监控 Matter 问题。
- 如何通过访问错误日志和收集信息来对错误进行分类。
- 如何访问 Matter 文档和支持资源以寻求帮助。
2. 查看 Google Home 分析
监控性能对于成功与 Google Home 生态系统集成至关重要。我们在 Google Cloud Platform 上为智能家居开发者提供了一套监控工具。您可以使用这些工具来衡量项目的效果。
访问项目指标
- 如需访问您的数据，第一步是查看 Google Home 信息中心，具体方法是登录 Google Cloud 控制台，然后依次前往运维 > 监控 > 信息中心。
您的项目（包括其他 GCP 产品）可以使用多个信息中心。为智能家居提供的信息中心带有 Google Home Analytics 前缀。
我们目前提供了一个涵盖整个项目的常规信息中心，以及适用于特定集成（Cloud、本地、Matter）或设备类型（摄像头）的信息中心。只有当您已完成相应类型的集成，并且有可满足请求的正常运行项目时，这些信息中心才会包含数据。
打开其中一个信息中心后，您会看到一系列类似以下的图表：
Google Home 信息中心包含各种图表，可显示与您的项目相关的事件的详细信息。在每个集成信息中心中，您会看到一个图表，显示项目处理的请求总数；一个图表，显示相应集成类型的成功率；以及几个图表，显示涉及的设备类型和特征。此外，借助 Matter，您可以使用一组图表来跟踪调试成功情况以及设备上的更新发布情况。
请注意，您在 Google Home Analytics 信息中心内看到的包含图表的默认视图只是我们使用智能家居指标数据为您的项目创建的一个视图。您还可以使用 Metrics Explorer 基于相同的基础指标创建自己的图表，并将其保存在自定义信息中心中。
访问错误日志
日志浏览器是一组用于处理项目中生成的事件日志的工具。您可以在 Google Cloud 控制台中访问该工具，方法是依次前往运维 > Logging > 日志浏览器。
打开日志浏览器后，您会看到如下所示的视图：
该浏览器窗口包含用于查看、过滤、查询和分析日志的各种工具。默认情况下，此视图会显示可供项目使用的所有系统生成的日志，包括在智能家居之外生成的日志。因此，使用这些日志时，请务必过滤出要调试的事件。我们将在调试部分对此进行详细介绍。
3. 调试配置问题
我们将首先介绍与 Matter 委托事件相关的第一类指标。调试是指用户首次设置 Matter 设备时需要执行的一组步骤。
在设备调试期间，Matter 设备、Google Home 应用和 Matter 网络之间会发生一组互动。下图展示了其中的一些事件：
您可以查看 Matter 入门手册中的配置页面，详细了解上述每个步骤。在本部分中，我们将介绍用于调试配置问题的工具和技术。
使用 Google Home 数据分析
我们创建了一组指标，以便您通过跟踪事件并了解错误可能发生在哪个阶段来调查配置问题。您可以在“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 服务检查您是否拥有 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"
}
每个错误日志都包含时间戳、设备类型和 trait，以及与 statusType 中的控制请求关联的错误。许多控制错误还包含 externalDebugString，这是一个简短的错误消息，用于说明错误的具体内容。
5. 调试其他功能
到目前为止，您已经学习了如何处理 Matter 设备的设备委托和控制问题。您还可以使用该生态系统中的其他功能或建议的技术来确保实现高质量的集成。
跟踪 OTA 更新
为了跟踪 Google Home 发布的 Matter 设备无线下载 (OTA) 更新的发布情况，我们提供了一组指标，用于显示现场设备的硬件和软件版本。
从控制台中发布更新后，请密切关注以下指标：
您会发现，在发布后的几天内，越来越多的现场设备会获得与您的 OTA 软件版本关联的新软件版本。
6. 寻求支持
Google 提供了一些工具和文档，可帮助您调试 Matter 问题，但由于 Matter 生态系统是新兴的，因此这些资源可能无法涵盖所有问题。在这种情况下，您可以随时与我们或社区联系寻求支持。
访问开发者渠道
Google 会主动监控三个开发者渠道：
虽然这些渠道均由同一团队定期监控，但在何时使用哪个渠道方面存在一些关键差异。
- Stack Overflow：如果您有实现方面的问题或需要寻求指导，可以与我们和智能家居开发者社区联系。此渠道最适合询问如何排查问题或实现某项功能。
- 问题跟踪器：这是 Google 运营的官方问题跟踪器系统，外部受众群体可以在此系统中报告生态系统中的错误。它提供了 Web 工具，可在需要时附加文件和分享敏感信息。如需报告生态系统问题或分享功能请求，最好使用问题跟踪器。
- 开发者论坛：如需向 Google 官方支持团队和社区专家寻求指导，您可以通过 Nest 开发者论坛与他们联系。此论坛最适合获取开发方面的官方指南。
订阅开发者简报
除了访问开发者渠道解答问题外，我们还会每季度发布一次简报，重点介绍新功能，并提供有关 Google 智能家居生态系统状态的最新资讯。
您可以使用注册表单接收开发者简报。
7. 恭喜
恭喜！您已成功学习如何使用我们推荐的工具和技术调试 Matter 集成。祝您顺利完成 Matter 与 Google Home 的集成。
后续步骤
尝试做以下练习并浏览其他资源：