遙測和疑難排解

空間分析包含一組功能，可監視系統的健康情況，並協助診斷問題。

啟用視覺效果

若要在視訊畫面中啟用 AI 見解事件的視覺效果，您需要在桌上型電腦或 Azure VM 上使用空間分析作業的 .debug 版本。 視覺效果不適用於 Azure Stack Edge 裝置。 有四個可用的偵錯作業。

如果您的裝置是本機桌上型電腦或 Azure GPU VM (已啟用遠端桌面)，則您可以切換至任何作業的 .debug 版本，並將輸出視覺化。

1. 在本機或使用執行空間分析的主機電腦上的遠端桌面用戶端，開啟桌面。

2. 在終端機中，執行 xhost +

3. 使用 DISPLAY 環境變數的值，更新 spaceanalytics 模組下的部署資訊清單。 在主機電腦上的終端機中執行 echo $DISPLAY，可以找到其值。

   "env": {        
       "DISPLAY": {
           "value": ":11"
           }
   }
   

4. 在您想要在偵錯模式下執行的部署資訊清單中，更新圖表。 在下列範例中，我們會將 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}]}"
        }
   }
   

5. 重新部署，您將會在主機電腦上看到視覺化檢視視窗

6. 完成部署之後，您可能必須將 .Xauthority 檔案從主機電腦複製到容器，然後將其重新啟動。 在下列範例中，peopleanalytics 是主機電腦上的容器名稱。

   sudo docker cp $XAUTHORITY peopleanalytics:/root/.Xauthority
   sudo docker stop peopleanalytics
   sudo docker start peopleanalytics
   xhost +
   

收集系統健康情況遙測

Telegraf 是可搭配空間分析使用的開放原始碼映像，而且可在 Microsoft Container Registry 中取得。 Telegraf 採用下列輸入，並將其傳送至 Azure 監視器。 您可以使用所需的自訂輸入和輸出，建置 Telegraf 模組。 空間分析中的 Telegraf 模組設定是部署資訊清單的一部分 (以上連結)。 此模組是選用的，如果不需要，可以從資訊清單中移除。

輸入：

• 空間分析計量
• 磁碟計量
• CPU 計量
• Docker 計量
• GPU 計量

輸出：

• Azure 監視器

提供的空間分析 Telegraf 模組會將空間分析容器發出的所有遙測資料發佈至 Azure 監視器。 如需有關將 Azure 監視器新增至訂用帳戶的詳細資訊，請參閱 Azure 監視器。

設定 Azure 監視器之後，您將需要建立可讓模組傳送遙測的認證。 您可以使用 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 監視器服務，或在 Azure 入口網站的 IoT 中樞選取 [監視]，存取回報的計量。

系統健康情況事件

針對 IoT Edge 裝置進行疑難排解

您可以使用 iotedge 命令列工具，檢查執行中模組的狀態和記錄。 例如：

• iotedge list：報告執行中模組的清單。 您可以使用 iotedge logs edgeAgent 進一步檢查錯誤。 如果 iotedge 停滯，您可以嘗試使用 iotedge restart edgeAgent 將其重新啟動
• iotedge logs <module-name>
• iotedge restart <module-name> 重新啟動特定模組

使用診斷容器收集記錄檔

空間分析會產生可供您用來診斷執行階段問題或包含在支援票證中的 Docker 偵錯記錄。 空間分析診斷模組在 Microsoft Container Registry 中，可供您下載。 在 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 環境變數設定為其中一個允許的值，以便在全域修改記錄層級。 您也可以在全域針對所有已部署的技能，或透過設定 platformLogLevel 和 nodesLogLevel 的值，以針對每個特定技能，透過 IoT Edge 模組對應項文件設定記錄層級，如下所示。

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

收集記錄

Azure Stack Edge 裝置、桌上型電腦或具有 GPU 的 Azure VM 的範例部署資訊清單檔包含一個名為 diagnostics 的模組，可收集和上傳記錄。 此模組預設為停用狀態，而且當您需要存取記錄時，應該透過 IoT Edge 模組設定來啟用。

diagnostics 集合可視需要透過 IoT Edge 直接方法控制，而且可以將記錄傳送至 Azure Blob 儲存體。

設定診斷上傳目標

從 IoT Edge 入口網站選取您的裝置，然後選取診斷模組。 在 Azure Stack Edge 裝置、桌上型電腦或具有 GPU 的 Azure VM 的範例部署資訊清單檔中，針對名為 env 的診斷，尋找 [環境變數] 區段，並新增下列資訊：

將上傳設定為 Azure Blob 儲存體

1. 建立您自己的 Azure Blob 儲存體帳戶 (如果您還沒有的話)。
2. 從 Azure 入口網站取得您儲存體帳戶的連接字串。 該字串位於存取金鑰中。
3. 空間分析記錄會自動上傳至名為 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 IoT Edge 方法，視需要上傳到 diagnostics 模組中。

1. 移至 IoT 中樞入口網站頁面，選取 [Edge 裝置]，然後選取您的裝置和診斷模組。
2. 移至模組的詳細資料頁面，然後選取 [直接方法] 索引標籤。
3. 在 [方法名稱] 上輸入 getRTCVLogs，並在承載中輸入 json 格式字串。 您可以輸入 {}，這表示空白承載。
4. 設定連線和方法逾時，然後選取 [叫用方法]。
5. 選取您的目標容器，並使用記錄語法一節中所述的參數，建置承載 json 字串。 選取 [叫用方法] 以執行要求。

記錄語法

下表列出查詢記錄時可使用的參數。

下表列出查詢回應中的屬性。

範例要求

{
    "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 端點。 

1. 在裝置的本機 UI 中，移至 [裝置] 頁面。
2. 在 [裝置端點] 底下，複製 Kubernetes API 服務端點。 此端點的字串為下列格式：https://compute..[device-IP-address]。
3. 儲存端點字串。 稍後設定 kubectl 存取 Kubernetes 叢集時，將會用到此資訊。

連線至 PowerShell 介面

從遠端 Windows 用戶端連線。 建立 Kubernetes 叢集之後，您可以透過此叢集管理應用程式。 您將需要連線至裝置的 PowerShell 介面。 視用戶端的作業系統而定，從遠端連線到裝置的程序可能有所不同。 下列步驟適用於執行 PowerShell 的 Windows 用戶端。

1. 以系統管理員身分執行 Windows PowerShell 工作階段。

   請確定您的用戶端上正在執行 Windows 遠端管理服務。 在命令提示字元中，輸入 winrm quickconfig。

2. 指派裝置 IP 位址的變數。 例如： $ip = "<device-ip-address>" 。

3. 使用下列命令，將裝置的 IP 位址新增至用戶端的受信任主機清單。

   Set-Item WSMan:\localhost\Client\TrustedHosts $ip -Concatenate -Force
   

4. 在裝置上啟動 Windows PowerShell 工作階段。

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

5. 出現提示時，請提供密碼。 使用與用來登入本機 Web 介面相同的密碼。 預設的本機 Web 介面密碼為 Password1。

存取 Kubernetes 叢集

建立 Kubernetes 叢集之後，您可以使用 kubectl 命令列工具存取叢集。

1. 建立新的命名空間。

   New-HcsKubernetesNamespace -Namespace
   

2. 建立使用者並取得組態檔。 此命令會輸出 Kubernetes 叢集的設定資訊。 複製此資訊，並將其儲存在名為 config 的檔案中。請勿以檔案副檔名來儲存檔案。

   New-HcsKubernetesUser -UserName
   

3. 將 config 檔案新增至本機電腦上使用者設定檔中的 .kube 資料夾。

4. 為命名空間與您建立的使用者建立關聯。

   Grant-HcsKubernetesNamespaceAccess -Namespace -UserName
   

5. 使用下列命令，在您的 Windows 用戶端上安裝 kubectl：

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

6. 將 DNS 項目新增至系統上的 hosts 檔案。

   1. 以系統管理員身分啟動 [記事本]，然後開啟位於 C:\windows\system32\drivers\etc\hosts 的 hosts 檔案。
   2. 在 hosts 檔案中建立一個項目，其中包含您從本機 UI 的 [裝置] 頁面取得的裝置 IP 位址和 DNS 網域。 您應該使用的端點類似如下：https://compute.asedevice.microsoftdatabox.com/10.100.10.10。

7. 確認您可以連線至 Kubernetes Pod。

   kubectl get pods -n "iotedge"
   

若要取得容器記錄，請執行下列命令：

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

實用的命令

如何針對空間分析提出支援票證

如果您需要更多支援來解決您遇到的空間分析容器問題，請依照下列步驟，填寫並提交支援票證。 我們的小組將為您提供進一步指導。

填寫基本資訊

在 [新增支援要求] 頁面建立新的支援票證。 依照提示，填寫下列參數：

1. 將 [問題類型] 設定為 Technical。
2. 選取您要用來部署空間分析容器的訂用帳戶。
3. 選取 My services 並選取 Azure AI services 作為服務。
4. 選取您要用來部署空間分析容器的資源。
5. 撰寫簡短的描述，詳述您遇到的問題。
6. 選取 Spatial Analysis 作為您的問題類型。
7. 從下拉式清單中選取適當的子類型。
8. 選取 [下一步: 解決方案]，移至下一頁。

建議的解決方案

下一個階段將提供您所選問題類型的建議解決方案。 這些解決方案將會解決最常見的問題，但如果對您的解決方案來說並不實用，請選取 [下一步: 詳細資料]，移至下一個步驟。

詳細資料

在此頁面上，新增一些有關您所遇到之問題的額外詳細資料。 請務必盡可能詳述細節，因為這可協助我們的工程師更清楚地縮小問題的範圍。 請著名您慣用的連絡方法和問題的嚴重性，讓我們可以適當地聯繫您，然後選取 [下一步: 檢閱 + 建立]，移至下一個步驟。

檢閱及建立

檢閱支援要求的詳細資料，以確保一切都正確無誤，並有效地呈現問題。 當您準備就緒時，選取 [建立]，將票證傳送給我們的小組！ 收到票證之後，您將會收到一封電子郵件確認，而且我們的小組會儘快回覆您。 您可以在 Azure 入口網站中檢視您票證的狀態。

下一步

• 設定空間分析作業
• 相機放置指南
• 區域和行放置指南