1. 准备工作
Matter 为最终用户提供顺畅的跨平台设备设置和控制体验。这主要是由于多个生态系统组件在后台协同运作。排查相关的问题排查问题对新开发者来说可能有些困难，因此我们开发了一系列工具和技术，让 Google Home 开发者能更轻松地成为 Matter 开发者。
此 Codelab 将介绍 Matter 的三个主要组件。对于所有这些系统，Google 都会针对从手机和 hub 中收集的开发者提供一套问题排查分析：
作为开发者，您必须能够缓解在整个设备开发周期内遇到的问题。项目启动后，您需要以汇总方式监控现场设备的问题趋势，并通过软件更新予以修复。此 Codelab 介绍了可同时用于这两种用途的技巧。
前提条件
- 完成 Matter 使用入门指南，了解如何使用有效的 Matter 项目和设备设置
- 拥有一台可连接到工作站（用于 ADB 日志）的 Android 手机
学习内容
- 如何使用智能家居分析工具来大规模监控 Matter 问题。
- 如何通过访问错误日志并收集信息对错误进行分类。
- 如何访问 Matter 文档和支持资源以寻求帮助。
2. 查看 Google Home Analytics（分析）
监控性能对于与 Google Home 生态系统成功集成至关重要。我们为 Google Cloud Platform 上的智能家居开发者提供了一组监控工具。您可以使用这些工具来衡量项目的性能。
访问项目指标
- 访问您的数据的第一步是检查 Google Home 信息中心，方法是登录 Google Cloud Console，然后依次转到操作 > 监控 > 信息中心。
你的项目可以使用很多信息中心（包括其他 GCP 产品）。为智能家居提供的信息中心带有一个前缀为 Google Home Analytics。
我们目前有一个涵盖整个项目的通用信息中心，以及针对特定集成（Cloud、Local、Matter）或设备类型（摄像头）的信息中心。只有当您集成了相应类型的数据，并且有正常运行的请求能够执行相应请求时，这些信息中心才会包含数据。
打开其中一个信息中心时，您会看到一系列图表，如下所示：
Google Home 信息中心包含各种图表，其中会显示与你的项目相关联的事件的详细信息。每个集成信息中心都会有一个图表显示项目处理的总请求次数，一个图表显示该集成类型的成功率，以及几个图表显示所涉及的设备类型和特征。此外，在 Matter 上，您还有一组图表可以跟踪调试成功与否，以及设备上的更新发布。
请注意，您在 Google Home Analytics 信息中心中看到的图表的默认视图只是我们使用智能家居指标数据为您的项目创建的视图。您还可以使用 Metrics Explorer 基于相同的基础指标创建自己的图表，并将其保存到自定义信息中心内。
访问错误日志
日志浏览器是一组处理项目生成的事件日志的工具。您可以在 Google Cloud 控制台中依次点击操作 > 日志记录 > 日志浏览器来访问该控制台。
打开日志浏览器后，您会看到如下所示的视图：
浏览器窗口包含用于查看、过滤、查询和分析日志的各种工具。默认情况下，此视图会显示你的项目提供的所有系统生成的日志，包括在智能家居外部生成的日志。因此，过滤日志是为了过滤要调试的事件。我们将在调试部分中对此进行详细介绍。
3. 调试调试问题
我们要介绍的第一种指标是 Matter 调试事件。调试是指用户首次设置 Matter 设备所需的一组步骤。
在设备调试期间，Matter 设备、Google Home 应用和 Matter 织物之间会发生一系列互动。下图演示了其中一些事件：
您可以参阅 Matter Primer 的“佣金”页面，详细了解每个步骤。在本部分中，我们将介绍用于调试调试问题的工具和技术。
使用 Google Home Analytics
我们创建了一系列指标，以便您通过跟踪事件并了解错误可能发生在哪个阶段来调查调试问题。您可以在 Matter 集成信息中心内找到这些 ID，如前一部分所述。
此信息中心内的图表提供了设备调试数据：
设备计数图表显示了用户在指定日期的调试次数。成功率显示的是 Google 端这些事件的感知成功率。每次调试尝试都会生成一组具有关联状态的事件。当其中任何一种状态出现错误时，相应错误也会记录在错误细分图表中。
调试状态：
- 已启动
- 上手使用载荷生成
- LOCAL_DISCOVERY_SUCCESSFUL
- ASE_CONNECTION_SUCCESSFUL
- NOC_ADDED_SUCCESSFULLY（NOC_已添加_成功）
- 完成佣金
如需查看这些事件的详细版本，请依次访问操作 > 日志记录 > 日志浏览器。如需过滤佣金错误，您可以在查询字段中搜索“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 服务检查您是否具有家居 / 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 设备控制问题也会在系统中生成一份错误日志。您可以通过搜索“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 运营的官方问题跟踪器系统，外部受众群体可在该系统中报告生态系统错误。它提供了一些 Web 工具，用于在需要时附加文件和共享敏感信息。使用问题跟踪器最适合报告生态系统问题或分享功能请求。
- 开发者论坛：如需向 Google 官方支持团队和社区专家寻求帮助，您可以通过 Nest 开发者论坛与我们联系。本论坛最适合用来获取开发方面的官方指导。
订阅开发者简报
除了访问开发者渠道进行咨询之外，我们还发布了季度简报，重点介绍新功能并提供有关 Google 智能家居生态系统状态的资讯。
您可以使用注册表单接收开发者简报。
7. 恭喜
恭喜！您已成功了解如何使用我们推荐的工具和技术调试 Matter 集成。希望您帮助 Google 构建 Matter 与 Google Home 的集成。
后续步骤
请尝试以下练习并探索其他资源：