【翻譯】.NET 6 中的 dotnet monitor

2021 年 12 月 6 日
筆記
.NET

我們在 2020 年 6 月首次推出了dotnet monitor 作為實驗工具，並在去年（2020年）努力將其轉變為生產級工具。今天，我很高興地的宣布 dotnet monitor 的第一個正式版將和 .NET 6 一起發佈，作為 .NET 6 的一部分。

dotnet monitor 已經為 Azure App Service（Linux）提供 .NET 應用程序的診斷工具提供支持，我們希望它在更多環境中使用。

一.什麼是 dotnet monitor

在不同的環境中運行 .NET 應用程序可能會使收集診斷信息（例如日誌、跟蹤、dump）變得困難。dotnet monitor 是一種工具，它提供了一種統一的方法來收集這些診斷信息，而不管您是在桌面計算機（desktop machine 可理解為我們日常使用的電腦）還是在 kubernetes 集群中運行。

收集這些診斷信息有兩種不同的機制：

按需收集診斷信息的 HTTP API。當您的應用程序遇到問題並且想收集更多信息時，可以調用這些 HTTP API。
基於規則配置的觸發器。您可以配置規則，以便在滿足所需條件時收集診斷信息，例如在 CPU 持續一段時間保持較高的指標時收集進程轉儲（process dump）。

二.入門

dotnet monitor 可以通過兩種不同的分發機制獲得：

.NET CLI 工具
通過 Microsoft Container Registry (MCR) 獲得的容器鏡像

.NET CLI 工具

dotnet monitor CLI 工具首先需要安裝 .NET 6 SDK，如果你沒有足夠新的 SDK，可以通過 .NET 下載網頁獲取安裝包進行安裝。

你可以使用一下命令獲取最新版的 dotnet monitor：

dotnet tool install -g dotnet-monitor --version 6.0.0

如果你已經安裝但是想更新到最新，可以運行以下命令：

dotnet tool update -g dotnet-monitor --version 6.0.0

容器鏡像

dotnet monitor 容器鏡像在 MCR 上可用，你可以通過以下命令獲取最新的鏡像：

docker pull mcr.microsoft.com/dotnet/monitor:6.0.0

三.HTTP API

dotnet monitor 公開了一個 HTTP API 來查詢可用進程、收集診斷信息並檢查請求信息的狀態。

暴露了以下 HTTP API：

/processes– 獲取可被發現的進程的詳細信息
/dump– 在不使用調試器的情況下捕獲進程的 dump
/gcdump– 捕獲進程的 GC dump
/trace– 不使用 profiler 來追蹤進程
/metrics– 以 Prometheus exposition 格式捕獲默認進程的指標快照
/livemetrics– 捕獲進程的實時指標流
/logs– 捕獲進程的日誌
/info– 獲取有關 dotnet monitor 的信息
/operations– 獲取操作狀態和取消操作

下面的示例演示如何使用 dotnet monitor 從目標進程開始，在60秒的時間內從Microsoft.AspNetCore.Server.Kestrel.Connections 日誌級別為 Debug 的日誌流數據。

PS> curl.exe -X POST "//localhost:52323/logs?name=myWebApp&durationSeconds=60" `
    -H "Accept: application/x-ndjson" `
    -H "Content-Type: application/json" `
    --negotiate -u $(whoami)`
    -d '{"filterSpecs": {"Microsoft.AspNetCore.Server.Kestrel.Connections": "Debug"}}' 

{"Timestamp":"2021-11-05 08:12:54Z","LogLevel":"Debug","EventId":39,"EventName":"ConnectionAccepted","Category":"Microsoft.AspNetCore.Server.Kestrel.Connections","Message":"Connection id u00220HMD06BUKL2CUu0022 accepted.","State":{"Message":"Connection id u00220HMD06BUKL2CUu0022 accepted.","ConnectionId":"0HMD06BUKL2CU","{OriginalFormat}":"Connection id u0022{ConnectionId}u0022 accepted."}}
{"Timestamp":"2021-11-05 08:12:54Z","LogLevel":"Debug","EventId":1,"EventName":"ConnectionStart","Category":"Microsoft.AspNetCore.Server.Kestrel.Connections","Message":"Connection id u00220HMD06BUKL2CUu0022 started.","State":{"Message":"Connection id u00220HMD06BUKL2CUu0022 started.","ConnectionId":"0HMD06BUKL2CU","{OriginalFormat}":"Connection id u0022{ConnectionId}u0022 started."}}
{"Timestamp":"2021-11-05 08:12:54Z","LogLevel":"Debug","EventId":9,"EventName":"ConnectionKeepAlive","Category":"Microsoft.AspNetCore.Server.Kestrel.Connections","Message":"Connection id u00220HMD06BUKL2CUu0022 completed keep alive response.","State":{"Message":"Connection id u00220HMD06BUKL2CUu0022 completed keep alive response.","ConnectionId":"0HMD06BUKL2CU","{OriginalFormat}":"Connection id u0022{ConnectionId}u0022 completed keep alive response."},"Scopes":[{"ConnectionId":"0HMD06BUKL2CU"},{"RequestId":"0HMD06BUKL2CU:00000002","RequestPath":"/"}]}

如上面的示例所示，您可以使用 dotnet monitor 按需從目標進程中捕獲診斷信息。除了日誌，您還可以從目標進程收集跟蹤、內存轉儲、GC轉儲和 metrics。

四.觸發器

dotnet monitor 可以配置為根據發現的進程中的條件自動收集診斷信息。發現新進程時，如果該進程數據與規則匹配，則 dotnet monitor 將嘗試應用配置的規則。應用的規則將開始監視觸發器描述的條件的過程。如果滿足該條件，則假定尚未達到指定的限制來執行操作列表。

示例：如果 dotnet monitor 檢測到持續超過一分鐘的CPU使用率在80%以上，則它將收集進程 dump，限制每小時不超過1個。

{
  "CollectionRules": {
    "HighCpuRule": {
      "Filters": [
        {
          "Key": "ProcessName",
          "Value": "MyApp",
          "MatchType": "Exact"
        }
      ],
      "Trigger": {
        "Type": "EventCounter",
        "Settings": {
          "ProviderName": "System.Runtime",
          "CounterName": "cpu-usage",
          "GreaterThan": 80,
          "SlidingWindowDuration": "00:01:00"
        }
      },
      "Limits": {
        "ActionCount": 1,
        "ActionCountSlidingWindowDuration": "1:00:00"
      },
      "Actions": [
        {
          "Type": "CollectDump",
          "Settings": {
            "Type": "Triage",
            "Egress": "myBlobStorageAccount"
          }
        }
      ]
    }
  }
}

規則文檔：//github.com/dotnet/dotnet-monitor/blob/main/documentation/collectionrules.md#collection-rules

五.反饋

github issue: //github.com/dotnet/dotnet-monitor/issues/new/choose

Tags: .NET