遥测和故障排除

项目
10/28/2024

空间分析包括一组功能，可用于监视系统的运行状况，并帮助解决诊断问题。

启用可视化

若要为视频帧中的 AI 见解事件启用可视化，需要在台式机或 Azure VM 上使用 .debug 版本的空间分析操作。在 Azure Stack Edge 设备上无法进行可视化。有四个可用的调试操作。

如果设备是本地台式机或 Azure GPU VM（已启用远程桌面），则可切换到任何操作的 .debug 版本并将输出可视化。

在本地打开桌面，或在运行空间分析的主计算机上使用远程桌面客户端打开桌面。
在终端中运行 xhost +
使用 DISPLAY 环境变量的值更新 spaceanalytics 模块下的部署清单。可以通过在主计算机上的终端中运行 echo $DISPLAY 来找到该值。
```
"env": {        
    "DISPLAY": {
        "value": ":11"
        }
}
```

更新要以调试模式运行的部署清单中的图形。在下面的示例中，我们将 operationId 更新为 cognitiveservices.vision.spatialanalysis-personcrossingpolygon.debug。需要新的 VISUALIZER_NODE_CONFIG 参数才能启用可视化工具窗口。所有操作都以调试风格提供。使用共享节点时，请使用cognitiveservices.vision.spatialanalysis.debug 操作并将 VISUALIZER_NODE_CONFIG 添加到实例参数。

"zonecrossing": {
     "operationId" : "cognitiveservices.vision.spatialanalysis-personcrossingpolygon.debug",
     "version": 1,
     "enabled": true,
     "parameters": {
         "VIDEO_URL": "Replace http url here",
         "VIDEO_SOURCE_ID": "zonecrossingcamera",
         "VIDEO_IS_LIVE": false,
        "VIDEO_DECODE_GPU_INDEX": 0,
         "DETECTOR_NODE_CONFIG": "{ \"gpu_index\": 0 }",
        "CAMERACALIBRATOR_NODE_CONFIG": "{ \"gpu_index\": 0}",
        "VISUALIZER_NODE_CONFIG": "{ \"show_debug_video\": true }",
         "SPACEANALYTICS_CONFIG": "{\"zones\":[{\"name\":\"queue\",\"polygon\":[[0.3,0.3],[0.3,0.9],[0.6,0.9],[0.6,0.3],[0.3,0.3]], \"threshold\":35.0}]}"
     }
}

重新部署，你将在主计算机上看到可视化工具窗口
部署完成后，可能需要将 .Xauthority 文件从主计算机复制到容器，然后重启容器。在以下示例中，peopleanalytics 是主计算机上的容器名称。
```
sudo docker cp $XAUTHORITY peopleanalytics:/root/.Xauthority
sudo docker stop peopleanalytics
sudo docker start peopleanalytics
xhost +
```

收集系统运行状况遥测数据

Telegraf 是可与空间分析配合使用的开源映像，它在 Microsoft 容器注册表中提供。它采用以下输入并将其发送到 Azure Monitor。可以使用所需的自定义输入和输出生成 Telegraf 模块。空间分析中的 Telegraf 模块配置是部署清单的一部分（在上面链接）。此模块是可选的，如果不需要它，可将其从清单中删除。

输入：

空间分析指标
磁盘指标
CPU 指标
Docker 指标
GPU 指标

输出：

Azure Monitor

提供的空间分析 Telegraf 模块会将空间分析容器发出的所有遥测数据发布到 Azure Monitor。有关将 Azure Monitor 添加到订阅的信息，请参阅 Azure Monitor。

设置 Azure Monitor 后，需要创建凭据，使模块能够发送遥测数据。可以使用 Azure 门户或以下 Azure CLI 命令创建新的服务主体。

注意

此命令要求你在订阅中拥有“所有者”特权。

# Find your Azure IoT Hub resource ID by running this command. The resource ID  should start with something like 
# "/subscriptions/b60d6458-1234-4be4-9885-c7e73af9ced8/resourceGroups/..."
az iot hub list

# Create a Service Principal with `Monitoring Metrics Publisher` role in the IoTHub resource:
# Save the output from this command. The values will be used in the deployment manifest. The password won't be shown again so make sure to write it down
az ad sp create-for-rbac --role="Monitoring Metrics Publisher" --name "<principal name>" --scopes="<resource ID of IoT Hub>"

在 Azure Stack Edge 设备、台式机或带有 GPU 的 Azure VM 的部署清单中找到 Telegraf 模块，将以下值替换为在上一步骤中获取的服务主体信息，然后重新部署。

"Telegraf": { 
  "settings": {
  "image":   "mcr.microsoft.com/azure-cognitive-services/vision/spatial-analysis/Telegraf:1.0",
  "createOptions":   "{\"HostConfig\":{\"Runtime\":\"nvidia\",\"NetworkMode\":\"azure-iot-edge\",\"Memory\":33554432,\"Binds\":[\"/var/run/docker.sock:/var/run/docker.sock\"]}}"
},
"type": "docker",
"env": {
    "AZURE_TENANT_ID": {
        "value": "<Tenant Id>"
    },
    "AZURE_CLIENT_ID": {
        "value": "Application Id"
    },
    "AZURE_CLIENT_SECRET": {
        "value": "<Password>"
    },
    "region": {
        "value": "<Region>"
    },
    "resource_id": {
        "value": "/subscriptions/{subscriptionId}/resourceGroups/{resoureGroupName}/providers/Microsoft.Devices/IotHubs/{IotHub}"
    },
...

部署 Telegraf 模块后，可以通过 Azure Monitor 服务或者通过在 Azure 门户上的 IoT 中心内选择“监视”来访问报告的指标。

Azure Monitor 遥测报告

系统运行状况事件

事件名称	描述
archon_exit	当用户将空间分析模块状态从“正在运行”更改为“已停止”时发送。
archon_error	当容器中的任何进程崩溃时发送。这是一个关键错误。
InputRate	图处理视频输入的速率。每五分钟报告一次。
OutputRate	图输出 AI 见解的速率。每五分钟报告一次。
archon_allGraphsStarted	所有图均已完成启动后发送。
archon_configchange	更改了图配置时发送。
archon_graphCreationFailed	当具有报告的 `graphId` 的图无法启动时发送。
archon_graphCreationSuccess	当具有报告的 `graphId` 的图成功启动时发送。
archon_graphCleanup	当具有报告的 `graphId` 的图完成清理并退出时发送。
archon_graphHeartbeat	每分钟为每个技能图发送的检测信号。
archon_apiKeyAuthFail	当视觉资源密钥出于以下原因，已超过 24 小时无法对容器进行身份验证时发送：超出配额、无效、脱机。
VideoIngesterHeartbeat	每小时发送一次，指示视频是从视频源流式传输的，并提供该小时内发生的错误数。针对每个图报告。
VideoIngesterState	报告视频流式传输的“已停止”或“已启动”状态。针对每个图报告。

排查 IoT Edge 设备问题

可以使用 iotedge 命令行工具来检查正在运行的模块的状态和日志。例如：

iotedge list：报告正在运行的模块的列表。可以使用 iotedge logs edgeAgent 进一步检查错误。如果 iotedge 停滞，你可以尝试使用 iotedge restart edgeAgent 将其重启
iotedge logs <module-name>
iotedge restart <module-name> 可重启特定的模块

使用诊断容器收集日志文件

空间分析生成 Docker 调试日志，你可以使用这些日志来诊断运行时问题，或将其包含在支持票证中。可供下载的空间分析诊断模块已在 Microsoft 容器注册表中提供。在 Azure Stack Edge 设备、台式机或带有 GPU 的 Azure VM 的清单部署文件中找到该诊断模块。

在“env”节中添加以下配置：

"diagnostics": {  
  "settings": {
  "image":   "mcr.microsoft.com/azure-cognitive-services/vision/spatial-analysis/diagnostics:1.0",
  "createOptions":   "{\"HostConfig\":{\"Mounts\":[{\"Target\":\"/usr/bin/docker\",\"Source\":\"/home/data/docker\",\"Type\":\"bind\"},{\"Target\":\"/var/run\",\"Source\":\"/run\",\"Type\":\"bind\"}],\"LogConfig\":{\"Config\":{\"max-size\":\"500m\"}}}}"
  }

若要优化上传到远程终结点（例如 Azure Blob 存储）的日志，我们建议保持较小的文件大小。请参阅以下示例来了解建议的 Docker 日志配置。

{
    "HostConfig": {
        "LogConfig": {
            "Config": {
                "max-size": "500m",
                "max-file": "1000"
            }
        }
    }
}

配置日志级别

使用日志级别配置可以控制生成的日志的详细程度。支持的日志级别为：none、verbose、info、warning 和 error。节点和平台的默认日志详细级别为 info。

可以通过将 ARCHON_LOG_LEVEL 环境变量设置为允许的值之一，来全局修改日志级别。还可以通过 IoT Edge 模块孪生文档为所有已部署的技能全局设置日志级别，或者按如下所示通过设置 platformLogLevel 和 nodesLogLevel 的值来为每个特定技能设置日志级别。

{
    "version": 1,
    "properties": {
        "desired": {
            "globalSettings": {
                "platformLogLevel": "verbose"
            },
            "graphs": {
                "samplegraph": {
                    "nodesLogLevel": "verbose",
                    "platformLogLevel": "verbose"
                }
            }
        }
    }
}

收集日志

注意

diagnostics 模块不影响日志记录内容，它只是帮助收集、筛选和上传现有的日志。必须具有 Docker API 1.40 或更高版本才能使用此模块。

Azure Stack Edge 设备、台式机或带有 GPU 的 Azure VM 的示例部署清单文件包含一个名为 diagnostics 的模块，该模块可收集和上传日志。此模块默认已禁用，当你需要访问日志时，应通过 IoT Edge 模块配置启用此模块。

diagnostics 收集是按需进行的，可通过 IoT Edge 直接方法对其进行控制；此收集模块可将日志发送到 Azure Blob 存储。

配置诊断上传目标

在 IoT Edge 门户中选择你的设备，然后选择“诊断”模块。在 Azure Stack Edge 设备、台式机或带有 GPU 的 Azure VM 的示例部署清单文件中，找到用于诊断的名为 env 的 Environment Variables 节，并在其中添加以下信息：

配置上传到 Azure Blob 存储

创建你自己的 Azure Blob 存储帐户（如果尚未这样做）。
从 Azure 门户获取你的存储帐户的连接字符串。它位于“访问密钥”中。
空间分析日志会自动上传到名为“rtcvlogs”的 Blob 存储容器，其文件名格式如下：{CONTAINER_NAME}/{START_TIME}-{END_TIME}-{QUERY_TIME}.log。

"env":{
    "IOTEDGE_WORKLOADURI":"fd://iotedge.socket",
    "AZURE_STORAGE_CONNECTION_STRING":"XXXXXX",   //from the Azure Blob Storage account
    "ARCHON_LOG_LEVEL":"info"
}

上传空间分析日志

在 getRTCVLogs 模块中使用 diagnostics IoT Edge 方法按需上传日志。

转到 IoT 中心门户页，选择“Edge 设备”，然后选择你的设备和诊断模块。
转到模块的详细信息页，选择“直接方法”选项卡。
在“方法名称”中键入 getRTCVLogs，在“有效负载”中键入 JSON 格式的字符串。可以输入 {}，表示空有效负载。
设置连接和方法超时，然后选择“调用方法”。
选择你的目标容器，并使用“日志记录语法”部分中所述的参数生成有效负载 JSON 字符串。选择“调用方法”以执行请求。

注意

结合空有效负载调用 getRTCVLogs 方法会返回设备上部署的所有容器的列表。方法名称区分大小写。如果提供了错误的方法名称，则你会收到 501 错误。

调用 getRTCVLogs 方法 getRTCVLogs 直接方法页面

日志记录语法

下表列出了查询日志时可以使用的参数。

关键字	说明	默认值
StartTime	所需的日志开始时间 (UTC)，以毫秒为单位。	`-1`，容器运行时的开始时间。将 `[-1.-1]` 用作时间范围时，API 将返回过去一小时的日志。
EndTime	所需的日志结束时间 (UTC)，以毫秒为单位。	`-1`，表示当前时间。使用 `[-1.-1]` 时间范围时，该 API 返回过去一小时的日志。
ContainerId	用于提取日志的目标容器。	没有容器 ID 时为 `null`。 API 将连同 ID 一起返回所有可用的容器信息。
DoPost	执行上传操作。如果此参数设置为 `false`，则会执行请求的操作并返回上传大小，但不执行上传。如果设置为 `true`，则会启动所选日志的异步上传	`false`，表示不上传
限制	指示要在每个批中上传多少行日志	`1000`，使用此参数可以调整发布速度。
筛选器	筛选要上传的日志	`null`，可以根据空间分析日志结构将筛选器指定为键值对：`[UTC, LocalTime, LOGLEVEL,PID, CLASS, DATA]`。例如：`{"TimeFilter":[-1,1573255761112]}, {"TimeFilter":[-1,1573255761112]}, {"CLASS":["myNode"]`

下表列出了查询响应中的特性。

关键字	说明
DoPost	true 或 false。指示日志是否已上传。选择不上传日志时，API 以同步方式返回信息。选择上传日志时，如果请求有效，则 API 返回 200，并开始以异步方式上传日志。
TimeFilter	应用于日志的时间筛选器。
ValueFilters	应用于日志的关键字筛选器。
时间戳	方法执行开始时间。
ContainerId	目标容器 ID。
FetchCounter	日志行总数。
FetchSizeInByte	日志数据总量，以字节为单位。
MatchCounter	有效的日志行数。
MatchSizeInByte	有效的日志数据量，以字节为单位。
FilterCount	应用筛选器后的日志行总数。
FilterSizeInByte	应用筛选器后的日志数据总量，以字节为单位。
FetchLogsDurationInMiliSec	提取操作持续时间。
PaseLogsDurationInMiliSec	筛选操作持续时间。
PostLogsDurationInMiliSec	发布操作持续时间。

示例请求

{
    "StartTime": -1,
    "EndTime": -1,
    "ContainerId": "5fa17e4d8056e8d16a5a998318716a77becc01b36fde25b3de9fde98a64bf29b",
    "DoPost": false,
    "Filters": null
}

示例响应

{
    "status": 200,
    "payload": {
        "DoPost": false,
        "TimeFilter": [-1, 1581310339411],
        "ValueFilters": {},
        "Metas": {
            "TimeStamp": "2020-02-10T04:52:19.4365389+00:00",
            "ContainerId": "5fa17e4d8056e8d16a5a998318716a77becc01b36fde25b3de9fde98a64bf29b",
            "FetchCounter": 61,
            "FetchSizeInByte": 20470,
            "MatchCounter": 61,
            "MatchSizeInByte": 20470,
            "FilterCount": 61,
            "FilterSizeInByte": 20470,
            "FetchLogsDurationInMiliSec": 0,
            "PaseLogsDurationInMiliSec": 0,
            "PostLogsDurationInMiliSec": 0
        }
    }
}

检查提取日志的行、时间和大小，如果这些设置看上去正确，请将 DoPost 替换为 true，以便将具有相同筛选器的日志推送到目标。

排查问题时，可以从 Azure Blob 存储导出日志。

排查 Azure Stack Edge 设备问题

以下部分旨在帮助你调试和验证 Azure Stack Edge 设备的状态。

访问 Kubernetes API 终结点。

在设备的本地 UI 中，转到“设备”页。
在“设备终结点”下，复制 Kubernetes API 服务终结点。此终结点是采用以下格式的字符串：https://compute..[device-IP-address]。
保存该终结点字符串。稍后在配置 kubectl 以访问 Kubernetes 群集时，你将使用此字符串。

连接到 PowerShell 界面

从 Windows 客户端远程连接。创建 Kubernetes 群集后，可以通过此群集管理应用程序。你需要连接到设备的 PowerShell 界面。远程连接到设备的过程根据客户端操作系统的不同而异。以下步骤适用于运行 PowerShell 的 Windows 客户端。

提示

在开始之前，请确保 Windows 客户端运行的是 Windows PowerShell 5.0 或更高版本。
也可以在 Linux 上使用 PowerShell。

以管理员身份运行 Windows PowerShell 会话。

确保 Windows 远程管理服务正在客户端上运行。在命令提示符下键入 winrm quickconfig。
为设备 IP 地址分配一个变量。例如，$ip = "<device-ip-address>"。
使用以下命令将设备的 IP 地址添加到客户端的受信任主机列表。
```
Set-Item WSMan:\localhost\Client\TrustedHosts $ip -Concatenate -Force
```

在设备上启动 Windows PowerShell 会话。

Enter-PSSession -ComputerName $ip -Credential $ip\EdgeUser -ConfigurationName Minishell

根据提示提供密码。使用登录到本地 Web 界面时所用的同一密码。默认的本地 Web 界面密码为 Password1。

访问 Kubernetes 群集

创建 Kubernetes 群集后，可以使用 kubectl 命令行工具访问该群集。

创建新命名空间。
```
New-HcsKubernetesNamespace -Namespace
```
创建一个用户并获取一个配置文件。此命令会输出 Kubernetes 群集的配置信息。复制此信息并将其保存到名为“config”的文件中。保存该文件时请不要指定文件扩展名。
```
New-HcsKubernetesUser -UserName
```
将 config 文件添加到本地计算机上你的用户配置文件中的 .kube 文件夹。

将命名空间与创建的用户相关联。

Grant-HcsKubernetesNamespaceAccess -Namespace -UserName

使用以下命令在你的 Windows 客户端上安装 kubectl：

curl https://storage.googleapis.com/kubernetesrelease/release/v1.15.2/bin/windows/amd64/kubectl.exe -O kubectl.exe

将 DNS 条目添加到系统上的 hosts 文件中。
1. 以管理员身份运行记事本，并打开位于 C:\windows\system32\drivers\etc\hosts 处的 hosts 文件。
2. 在 hosts 文件中创建一个条目，并在其中包含你从本地 UI 的“设备”页获取的设备 IP 地址和 DNS 域。应使用的终结点类似于：https://compute.asedevice.microsoftdatabox.com/10.100.10.10。
验证是否可以连接到 Kubernetes Pod。
```
kubectl get pods -n "iotedge"
```

若要获取容器日志，请运行以下命令：

kubectl logs <pod-name> -n <namespace> --all-containers

有用的命令

命令	说明
`Get-HcsKubernetesUserConfig -AseUser`	生成 Kubernetes 配置文件。使用该命令时，请将信息复制到名为 config 的文件中。保存该文件时请不要指定文件扩展名。
`Get-HcsApplianceInfo`	返回有关你的设备的信息。
`Enable-HcsSupportAccess`	生成访问凭据以启动支持会话。

通过