共用方式為

Orleans 可檢視性

  • 發行項

分散式系統的其中一個最重要的層面是可檢視性。 可檢視性是在任何指定時間了解系統狀態的能力。 有各種方式可以達成此目的，包括記錄、計量和分散式追蹤。

記錄

Orleans 會針對所有定址接收器和用戶端記錄使用 Microsoft.Extensions.Logging。 您可以使用與 Microsoft.Extensions.Logging 相容的任何記錄提供者。 應用程式程式碼會依賴相依性插入來取得 ILogger<TCategoryName> 的執行個體，並使用其來記錄訊息。 如需詳細資訊，請參閱 以 .NET 記錄。

計量

計量是一段時間所報告的數值計量。 其最常用來監視應用程式的健康情況，並產生警示。 如需詳細資訊，請參閱 .NET 中的計量。 Orleans 會使用 System.Diagnostics.Metrics API 來收集計量。 計量會公開至 OpenTelemetry 專案，此專案會將計量匯出至各種監視系統。

若要監視應用程式，而不進行任何程式碼變更，您可以使用 dotnet counters .NET 診斷工具。 若要監視 OrleansActivitySource 計數器，假設您希望 <ProcessName> 進行監視，請如下所示，使用 dotnet counters monitor 命令：

dotnet counters monitor -n <ProcessName> --counters Microsoft.Orleans

想像您正在執行 OrleansGPS 追蹤器範例應用程式，而在另一個終端機中，您會使用 dotnet counters monitor 命令來進行監視。 以下是典型的輸出：

Press p to pause, r to resume, q to quit.
    Status: Running
[Microsoft.Orleans]
    orleans-app-requests-latency-bucket (Count / 1 sec)                    0
        duration=10000ms                                                   0
        duration=1000ms                                                    0
        duration=100ms                                                     0
        duration=10ms                                                      0
        duration=15000ms                                                   0
        duration=1500ms                                                    0
        duration=1ms                                                   2,530
        duration=2000ms                                                    0
        duration=200ms                                                     0
        duration=2ms                                                       0
        duration=400ms                                                     0
        duration=4ms                                                       0
        duration=5000ms                                                    0
        duration=50ms                                                      0
        duration=6ms                                                       0
        duration=800ms                                                     0
        duration=8ms                                                       0
        duration=9223372036854775807ms                                     0
    orleans-app-requests-latency-count (Count / 1 sec)                 2,530
    orleans-app-requests-latency-sum (Count / 1 sec)                       0
    orleans-catalog-activation-working-set                                36
    orleans-catalog-activations                                           38
    orleans-consistent-ring-range-percentage-average                     100
    orleans-consistent-ring-range-percentage-local                       100
    orleans-consistent-ring-size                                           1
    orleans-directory-cache-size                                          27
    orleans-directory-partition-size                                      26
    orleans-directory-ring-local-portion-average-percentage              100
    orleans-directory-ring-local-portion-distance                          0
    orleans-directory-ring-local-portion-percentage                        0
    orleans-directory-ring-size                                        1,295
    orleans-gateway-received (Count / 1 sec)                           1,291
    orleans-gateway-sent (Count / 1 sec)                               2,582
    orleans-messaging-processing-activation-data                           0
    orleans-messaging-processing-dispatcher-forwarded (Count / 1           0
    orleans-messaging-processing-dispatcher-processed (Count / 1       2,543
        Direction=Request,Status=Ok                                    2,582
    orleans-messaging-processing-dispatcher-received (Count / 1        1,271
        Context=Grain,Direction=Request                                1,291
        Context=None,Direction=Request                                 1,291
    orleans-messaging-processing-ima-enqueued (Count / 1 sec)          5,113

如需詳細資訊，請參閱調查效能計數器 (dotnet-counters)。

Orleans 計量

Orleans 會使用 System.Diagnostics.Metrics API 來收集計量。 Orleans 會將每個計量分類為以網域為中心的關注點，例如網路、傳訊、閘道等等。 下列小節描述 Orleans 所使用的計量。

網路

下表代表用來監視 Orleans 網路層的網路計量集合。

計量名稱 類型 描述
orleans-networking-sockets-closed Counter<T> 已關閉的通訊端計數。
orleans-networking-sockets-opened Counter<T> 已開啟的通訊端計數。

傳訊

下表代表用來監視 Orleans 傳訊層的傳訊計量集合。

計量名稱 類型 描述
orleans-messaging-sent-messages-size Histogram<T> 長條圖，表示已傳送的訊息大小 (以位元組為單位)。
orleans-messaging-received-messages-size Histogram<T> 長條圖，表示已接收的訊息大小 (以位元組為單位)。
orleans-messaging-sent-header-size ObservableCounter<T> 可觀察計數器，表示已傳送的標頭位元組數目。
orleans-messaging-received-header-size ObservableCounter<T> 可觀察計數器，表示已接收的標頭位元組數目。
orleans-messaging-sent-failed Counter<T> 傳送訊息失敗的計數。
orleans-messaging-sent-dropped Counter<T> 捨棄已傳送訊息的計數。
orleans-messaging-processing-dispatcher-received ObservableCounter<T> 可觀察計數器，表示發送器已接收的訊息數目。
orleans-messaging-processing-dispatcher-processed ObservableCounter<T> 可觀察計數器，表示發送器已處理的訊息數目。
orleans-messaging-processing-dispatcher-forwarded ObservableCounter<T> 可觀察計數器，表示發送器已轉送的訊息數目。
orleans-messaging-processing-ima-received ObservableCounter<T> 可觀察計數器，表示已接收的傳入訊息數目。
orleans-messaging-processing-ima-enqueued ObservableCounter<T> 可觀察計數器，表示已加入佇列的傳入訊息數目。
orleans-messaging-processing-activation-data ObservableGauge<T> 可觀察量測計，表示所有處理中的啟用資料。
orleans-messaging-pings-sent Counter<T> 已傳送的 Ping 計數。
orleans-messaging-pings-received Counter<T> 已接收的 Ping 計數。
orleans-messaging-pings-reply-received Counter<T> 已接收的 Ping 回覆計數。
orleans-messaging-pings-reply-missed Counter<T> 遺漏的 Ping 回覆計數。
orleans-messaging-expired" Counter<T> 已過期的訊息計數。
orleans-messaging-rejected Counter<T> 已拒絕的訊息計數。
orleans-messaging-rerouted Counter<T> 已重新路由傳送的訊息計數。
orleans-messaging-sent-local ObservableCounter<T> 可觀察計數器，表示已傳送的本機訊息數目。

閘道

下表代表用來監視 Orleans 閘道層的閘道計量集合。

計量名稱 類型 描述
orleans-gateway-connected-clients UpDownCounter<T> 表示已連線用戶端數目的上/下計數器。
orleans-gateway-sent Counter<T> 已傳送的閘道訊息計數。
orleans-gateway-received Counter<T> 已接收的閘道訊息計數。
orleans-gateway-load-shedding Counter<T> 由於閘道多載而遭到拒絕的閘道 (減載) 計數訊息。

執行階段

下表代表用來監視 Orleans 執行階段層的執行階段計量集合。

計量名稱 類型 描述
orleans-scheduler-long-running-turns Counter<T> 排程器內的長時間執行回合計數。
orleans-runtime-total-physical-memory ObservableCounter<T> 可觀察計數器，表示 Orleans 執行階段的記憶體總數 (以 MB 為單位)。
orleans-runtime-available-memory ObservableCounter<T> 可觀察計數器，表示 Orleans 執行階段的可用記憶體 (以 MB 為單位)。

目錄

下表代表用來監視 Orleans 目錄層的目錄計量集合。

計量名稱 類型 描述
orleans-catalog-activations ObservableGauge<T> 可觀察量測計，表示目錄啟用次數。
orleans-catalog-activation-working-set ObservableGauge<T> 可觀察量測計，表示工作集內的啟用次數。
orleans-catalog-activation-created Counter<T> 已建立的啟用計數。
orleans-catalog-activation-destroyed Counter<T> 已終結的啟用計數。
orleans-catalog-activation-failed-to-activate Counter<T> 無法啟動的啟用計數。
orleans-catalog-activation-collections Counter<T> 閒置啟用集合的計數。
orleans-catalog-activation-shutdown Counter<T> 關機啟用計數。
orleans-catalog-activation-non-existent Counter<T> 不存在的啟用計數。
orleans-catalog-activation-concurrent-registration-attempts Counter<T> 並行啟用註冊嘗試的計數。

Directory

下表代表用來監視 Orleans 目錄層的目錄計量集合。

計量名稱 類型 描述
orleans-directory-lookups-local-issued Counter<T> 已發出的本機查閱計數。
orleans-directory-lookups-local-successes Counter<T> 本機成功查閱的計數。
orleans-directory-lookups-full-issued Counter<T> 已發出的完整目錄查閱計數。
orleans-directory-lookups-remote-sent Counter<T> 已傳送的遠端目錄查閱計數。
orleans-directory-lookups-remote-received Counter<T> 已接收的遠端目錄查閱計數。
orleans-directory-lookups-local-directory-issued Counter<T> 已發出的本機目錄查閱計數。
orleans-directory-lookups-local-directory-successes Counter<T> 本機目錄成功查閱的計數。
orleans-directory-lookups-cache-issued Counter<T> 已發出的快取查閱計數。
orleans-directory-lookups-cache-successes Counter<T> 快取成功查閱的計數。
orleans-directory-validations-cache-sent Counter<T> 已傳送的目錄快取驗證計數。
orleans-directory-validations-cache-received Counter<T> 已接收的目錄快取驗證計數。
orleans-directory-partition-size ObservableGauge<T> 可觀察量測計，表示目錄磁碟分割大小。
orleans-directory-cache-size ObservableGauge<T> 可觀察量測計，表示目錄快取大小。
orleans-directory-ring-size ObservableGauge<T> 可觀察量測計，表示目錄通道大小。
orleans-directory-ring-local-portion-distance ObservableGauge<T> 可觀察量測計，表示本機目錄磁碟分割所擁有的通道範圍。
orleans-directory-ring-local-portion-percentage ObservableGauge<T> 可觀察量測計，表示本機目錄所擁有的通道範圍，以總計範圍的百分比表示。
orleans-directory-ring-local-portion-average-percentage ObservableGauge<T> 可觀察量測計，表示每個尋址接收器所擁有的目錄通道範圍平均百分比，這表示目錄所有權的平衡程度。
orleans-directory-registrations-single-act-issued Counter<T> 已發出的目錄單一啟用註冊計數。
orleans-directory-registrations-single-act-local Counter<T> 本機目錄磁碟分割所處理的目錄單一啟用註冊計數。
orleans-directory-registrations-single-act-remote-sent Counter<T> 已傳送至遠端目錄磁碟分割的目錄單一啟用註冊計數。
orleans-directory-registrations-single-act-remote-received Counter<T> 已從遠端主機接收的目錄單一啟用註冊計數。
orleans-directory-unregistrations-issued Counter<T> 已發出的目錄取消註冊計數。
orleans-directory-unregistrations-local Counter<T> 本機目錄磁碟分割所處理的目錄取消註冊計數。
orleans-directory-unregistrations-remote-sent Counter<T> 已傳送至遠端目錄磁碟分割的目錄取消註冊計數。
orleans-directory-unregistrations-remote-received Counter<T> 已從遠端主機接收的目錄取消註冊計數。
orleans-directory-unregistrations-many-issued Counter<T> 已發出的目錄多重啟用取消註冊計數。
orleans-directory-unregistrations-many-remote-sent Counter<T> 已傳送至遠端目錄磁碟分割的目錄多重啟用取消註冊計數。
orleans-directory-unregistrations-many-remote-received Counter<T> 已從遠端主機接收的目錄多重啟用取消註冊計數。

一致通道

下表代表用來監視 Orleans 一致通道層的一致通道計量集合。

計量名稱 類型 描述
orleans-consistent-ring-size ObservableGauge<T> 可觀察量測計，表示一致通道大小。
orleans-consistent-ring-range-percentage-local ObservableGauge<T> 可觀察量測計，表示一致通道本機百分比。
orleans-consistent-ring-range-percentage-average ObservableGauge<T> 可觀察量測計，表示一致通道平均百分比。

監看程式

下表代表用來監視 Orleans 監看程式層的監看程式計量集合。

計量名稱 類型 描述
orleans-watchdog-health-checks Counter<T> 監看程式健康情況檢查的計數。
orleans-watchdog-health-checks-failed Counter<T> 監看程式健康情況檢查失敗的計數。

用戶端

下表代表用來監視 Orleans 用戶端層的用戶端計量集合。

計量名稱 類型 描述
orleans-client-connected-gateways ObservableGauge<T> 可觀察量測計，表示已連線閘道用戶端的數目。

其他

下表代表用來監視各種圖層的其他計量集合。

計量名稱 類型 描述
orleans-grains Counter<T> 表示粒紋數目的計數。
orleans-system-targets Counter<T> 表示系統目標數目的計數。

應用程式要求

下表代表用來監視 Orleans 應用程式要求層的應用程式要求計量集合。

計量名稱 類型 描述
orleans-app-requests-latency ObservableCounter<T> 可觀察計數器，表示應用程式要求延遲。
orleans-app-requests-timedout ObservableCounter<T> 可觀察計數器，表示已逾時的應用程式要求。

提醒

下表代表用來監視 Orleans 提醒層的提醒計量集合。

計量名稱 類型 描述
orleans-reminders-tardiness Histogram<T> 長條圖，表示提醒遲到的秒數。
orleans-reminders-active ObservableGauge<T> 可觀察量測計，表示作用中提醒的數目。
orleans-reminders-ticks-delivered Counter<T> 計數，表示已傳遞的提醒刻度數目。

儲存體

下表代表用來監視 Orleans 儲存體層的儲存體計量集合。

計量名稱 類型 描述
orleans-storage-read-errors Counter<T> 計數，表示儲存體讀取錯誤的數目。
orleans-storage-write-errors Counter<T> 計數，表示儲存體寫入錯誤的數目。
orleans-storage-clear-errors Counter<T> 計數，表示儲存體清除錯誤的數目。
orleans-storage-read-latency Histogram<T> 長條圖，表示儲存體讀取延遲 (以毫秒為單位)。
orleans-storage-write-latency Histogram<T> 長條圖，表示儲存體寫入延遲 (以毫秒為單位)。
orleans-storage-clear-latency Histogram<T> 長條圖，表示儲存體清除延遲 (以毫秒為單位)。

資料流

下表代表用來監視 Orleans 串流層的串流計量集合。

計量名稱 類型 描述
orleans-streams-pubsub-producers-added Counter<T> 已新增的串流 PubSub 生產者計數。
orleans-streams-pubsub-producers-removed Counter<T> 已移除的串流 PubSub 生產者計數。
orleans-streams-pubsub-producers Counter<T> 串流 PubSub 生產者計數。
orleans-streams-pubsub-consumers-added Counter<T> 已新增的串流 PubSub 消費者計數。
orleans-streams-pubsub-consumers-removed Counter<T> 已移除的串流 PubSub 消費者計數。
orleans-streams-pubsub-consumers Counter<T> 串流 PubSub 消費者計數。
orleans-streams-persistent-stream-pulling-agents ObservableGauge<T> 可觀察量測計，表示永續性串流提取代理程式的數目。
orleans-streams-persistent-stream-messages-read Counter<T> 已讀取的永續性串流訊息計數。
orleans-streams-persistent-stream-messages-sent Counter<T> 已傳送的永續性串流訊息計數。
orleans-streams-persistent-stream-pubsub-cache-size ObservableGauge<T> 可觀察量測計，表示永續性串流 PubSub 快取大小。
orleans-streams-queue-initialization-failures Counter<T> 資料流佇列初始化失敗計數。
orleans-streams-queue-initialization-duration Counter<T> 資料流佇列初始化發生計數。
orleans-streams-queue-initialization-exceptions Counter<T> 資料流佇列初始化例外狀況計數。
orleans-streams-queue-read-failures Counter<T> 資料流佇列讀取失敗計數。
orleans-streams-queue-read-duration Counter<T> 資料流佇列讀取發生計數。
orleans-streams-queue-read-exceptions Counter<T> 資料流佇列讀取例外狀況計數。
orleans-streams-queue-shutdown-failures Counter<T> 資料流佇列關機失敗計數。
orleans-streams-queue-shutdown-duration Counter<T> 資料流佇列關機發生計數。
orleans-streams-queue-shutdown-exceptions Counter<T> 資料流佇列關機例外狀況計數。
orleans-streams-queue-messages-received ObservableCounter<T> 可觀察計數器，表示已接收的串流佇列訊息數目。
orleans-streams-queue-oldest-message-enqueue-age ObservableGauge<T> 可觀察量測計，表示最早加入佇列訊息的存留期。
orleans-streams-queue-newest-message-enqueue-age ObservableGauge<T> 可觀察量測計，表示最新加入佇列訊息的存留期。
orleans-streams-block-pool-total-memory ObservableCounter<T> 可觀察計數器，表示串流區塊集區總記憶體 (以位元組為單位)。
orleans-streams-block-pool-available-memory ObservableCounter<T> 可觀察計數器，表示串流區塊集區可用記憶體 (以位元組為單位)。
orleans-streams-block-pool-claimed-memory ObservableCounter<T> 可觀察計數器，表示串流區塊集區要求的記憶體 (以位元組為單位)。
orleans-streams-block-pool-released-memory ObservableCounter<T> 可觀察計數器，表示串流區塊集區釋出的記憶體 (以位元組為單位)。
orleans-streams-block-pool-allocated-memory ObservableCounter<T> 可觀察計數器，表示串流區塊集區配置的記憶體 (以位元組為單位)。
orleans-streams-queue-cache-size ObservableCounter<T> 可觀察計數器，表示串流佇列快取大小 (以位元組為單位)。
orleans-streams-queue-cache-length ObservableCounter<T> 可觀察計數器，表示串流佇列長度。
orleans-streams-queue-cache-messages-added ObservableCounter<T> 可觀察計數器，表示已新增的串流佇列訊息。
orleans-streams-queue-cache-messages-purged ObservableCounter<T> 可觀察計數器，表示已清除的串流佇列訊息。
orleans-streams-queue-cache-memory-allocated ObservableCounter<T> 可觀察計數器，表示已配置的串流佇列記憶體。
orleans-streams-queue-cache-memory-released ObservableCounter<T> 可觀察計數器，表示已釋出的串流佇列記憶體。
orleans-streams-queue-cache-oldest-to-newest-duration ObservableGauge<T> 可觀察量測計，表示從最舊到最新串流佇列快取的持續時間。
orleans-streams-queue-cache-oldest-age ObservableGauge<T> 可觀察量測計，表示最舊快取訊息的存留期。
orleans-streams-queue-cache-pressure ObservableGauge<T> 可觀察量測計，表示串流佇列快取的壓力。
orleans-streams-queue-cache-under-pressure ObservableGauge<T> 可觀察量測計，表示串流佇列快取是否處於壓力下。
orleans-streams-queue-cache-pressure-contribution-count ObservableCounter<T> 可觀察計數器，表示串流佇列快取壓力貢獻。

交易

下表代表用來監視 Orleans 交易層的交易計量集合。

計量名稱 類型 描述
orleans-transactions-started ObservableCounter<T> 可觀察計數器，表示已啟動的交易數目。
orleans-transactions-successful ObservableCounter<T> 可觀察計數器，表示成功交易數目。
orleans-transactions-failed ObservableCounter<T> 可觀察計數器，表示失敗交易數目。
orleans-transactions-throttled ObservableCounter<T> 可觀察計數器，表示節流交易數目。

Prometheus

有各種您可以與 Orleans 搭配使用的協力廠商計量提供者。 其中一個熱門的範例是 Prometheus，可用來搭配 OpenTelemetry 收集應用程式中的計量。

若要將 Orleans 與 OpenTelemetry 和 Prometheus 搭配使用，請呼叫下列 IServiceCollection 擴充方法：

builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics =>
    {
        metrics
            .AddPrometheusExporter()
            .AddMeter("Microsoft.Orleans");
    });

重要

OpenTelemetry.Exporter.Prometheus 和 OpenTelemetry.Exporter.Prometheus.AspNetCore NuGet 套件目前處於預覽狀態，作為候選版。 在實際使用時不建議這樣做。

AddPrometheusExporter 方法可確保已將 PrometheusExporter 新增至 builder。 Orleans 使用具名 "Microsoft.Orleans" 的 Meter 來建立許多 Orleans 特定計量的 Counter<T> 執行個體。 AddMeter 方法可用來指定要訂閱的計量名稱，在此案例中為 "Microsoft.Orleans"。

設定匯出工具並建置應用程式之後，您必須在 IEndpointRouteBuilder (app 執行個體) 上呼叫 MapPrometheusScrapingEndpoint，以將計量公開給 Prometheus。 例如：

WebApplication app = builder.Build();

app.MapPrometheusScrapingEndpoint();
app.Run();

分散式追蹤

分散式追蹤是一組工具和做法，可用來監視分散式應用程式和進行疑難排解。 分散式追蹤是可檢視性的重要元件，也是開發人員了解其應用程式行為的重要工具。 Orleans 也支援使用 OpenTelemetry 的分散式追蹤。

無論選擇的分散式追蹤匯出工具為何，您都會呼叫：

回到 OrleansGPS 追蹤器範例應用程式，您可以使用 Zipkin 分散式追蹤系統，透過更新 Program.cs 來監視應用程式。 若要將 Orleans 與 OpenTelemetry 和 Zipkin 搭配使用，請呼叫下列 IServiceCollection 擴充方法：

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        // Set a service name
        tracing.SetResourceBuilder(
            ResourceBuilder.CreateDefault()
                .AddService(serviceName: "GPSTracker", serviceVersion: "1.0"));

        tracing.AddSource("Microsoft.Orleans.Runtime");
        tracing.AddSource("Microsoft.Orleans.Application");

        tracing.AddZipkinExporter(zipkin =>
        {
            zipkin.Endpoint = new Uri("http://localhost:9411/api/v2/spans");
        });
    });

重要

OpenTelemetry.Exporter.Zipkin NuGet 套件目前處於預覽狀態，作為候選版。 在實際使用時不建議這樣做。

Zipkin 追蹤會顯示在 Jaeger UI (這是 Zipkin 的替代方案，但使用的資料格式是相同的)：

Orleans GPS Tracker sample app: Jaeger UI trace.

如需詳細資訊，請參閱分散式追蹤。

Orleans 透過 ITelemetryConsumer 介面輸出其執行階段統計資料和計量。 應用程式可以為其定址接收器和用戶端註冊一或多個遙測取用者，以接收 Orleans 執行階段定期發佈的統計資料和計量。 這些可以是熱門遙測分析解決方案的取用者，或用於任何其他目的地和用途的自訂解決方案。 Orleans 程式碼基底中目前包含三個遙測取用者。

其會以個別的 NuGet 套件的形式發行：

  • Microsoft.Orleans.OrleansTelemetryConsumers.AI 用於發佈至 Azure Application Insights。

  • Microsoft.Orleans.OrleansTelemetryConsumers.Counters 用於發佈至 Windows 效能計數器。 Orleans 執行階段會持續更新它們。 Microsoft.Orleans.CounterControl NuGet 套件中包含的 CounterControl.exe 工具可協助註冊必要的效能計數器類別。 必須以較高的權限執行。 您可以使用任何標準監視工具來監視效能計數器。

  • Microsoft.Orleans.OrleansTelemetryConsumers.NewRelic 用於發佈至 New Relic。

若要將定址接收器和用戶端設定為使用遙測取用者，定址接收器設定程式碼看起來如下：

var siloHostBuilder = new HostBuilder()
    .UseOrleans(c =>
    {
        c.AddApplicationInsightsTelemetryConsumer("INSTRUMENTATION_KEY");
    });

用戶端設定程式碼看起來像這樣：

var clientBuilder = new ClientBuilder();
clientBuilder.AddApplicationInsightsTelemetryConsumer("INSTRUMENTATION_KEY");

若要使用自訂定義 TelemetryConfiguration (可能有 TelemetryProcessors、TelemetrySinks 等)，定址接收器設定程式碼如下所示：

var telemetryConfiguration = TelemetryConfiguration.CreateDefault();
var siloHostBuilder = new HostBuilder()
    .UseOrleans(c =>
    {
        c.AddApplicationInsightsTelemetryConsumer(telemetryConfiguration);
    });

用戶端設定程式碼看起來像這樣：

var clientBuilder = new ClientBuilder();
var telemetryConfiguration = TelemetryConfiguration.CreateDefault();
clientBuilder.AddApplicationInsightsTelemetryConsumer(telemetryConfiguration);

另請參閱