.NET 中的記錄取樣

2025-05-22

.NET 提供記錄取樣功能，可讓您控制應用程式發出的記錄量，而不會遺失重要資訊。下列取樣策略可供使用：

追蹤型取樣：根據當前追蹤的取樣決策對記錄進行取樣。
隨機概率取樣：根據已設定的機率規則取樣記錄。
自定義取樣：實作您自己的自定義取樣策略。如需詳細資訊，請參閱實作自定義取樣。

備註

一次只能使用一個取樣器。如果您註冊多個取樣器，則會使用最後一個取樣器。

記錄取樣可讓您更精細地控制應用程式發出的記錄，藉此擴充篩選功能。您可以設定取樣率，只記錄一小部分日志，而不是僅僅啟用或停用日志。

例如，雖然篩選通常會使用像是0（不發出任何記錄）或1（發出所有記錄）等機率，但取樣可讓您選擇介於兩者之間的任何值，例如0.1來發出 10%% 的記錄，或0.25發出 25%%的記錄。

開始吧

若要開始使用，請安裝 📦 Microsoft.Extensions.Telemetry NuGet 套件：

.NET CLI
套件參考

dotnet add package Microsoft.Extensions.Telemetry

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Telemetry"
                    Version="*" />
</ItemGroup>

如需詳細資訊，請參閱 dotnet 新增套件或在 .NET 應用程式中管理套件相依性。

設定追蹤型取樣

追蹤型取樣可確保記錄會與基礎 Activity一致地取樣。當您想要維護追蹤與記錄之間的相互關聯時，這會很有用。您可以啟用跟蹤取樣（如《指南》所述），然後相應配置基於跟蹤的日誌取樣：

builder.Logging.AddTraceBasedSampler();

啟用追蹤式取樣時，只有在底層 Activity 被取樣時，才會發出記錄。取樣決策來自目前的 Recorded 值。

設定隨機概率取樣

隨機概率取樣可讓您根據設定的機率規則來取樣記錄。您可以定義下列特定規則：

記錄類別
記錄等級
事件識別碼

有數種方式可以使用其規則來設定隨機概率取樣：

以檔案為基礎的設定

在您的 appsettings.json中建立組態區段，例如：

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    }
  },

  "RandomProbabilisticSampler": {
    "Rules": [
      {
        "CategoryName": "Microsoft.AspNetCore.*",
        "Probability": 0.25,
        "LogLevel": "Information"
      },
      {
        "CategoryName": "System.*",
        "Probability": 0.1
      },
      {
        "EventId": 1001,
        "Probability": 0.05
      }
    ]
  }
}

上述組態：

從所有層級中類別名稱以 System. 開頭的記錄中, 抽取樣本 10%。
從 Microsoft.AspNetCore. 開始 LogLevel.Information 類別中的日誌 25% 範例。
範例 5% 所有類別和層級的事件標識碼為 1001 的記錄。
從其他所有日誌中抽取 100 個% 样本。

這很重要

值 Probability 代表值為 0 到 1 的機率。例如，0.25 表示將會取樣 25% 的記錄。 0 表示不會取樣任何記錄，1 表示會取樣所有記錄。具有 0 和 1 的案例可用來有效停用或啟用特定規則的所有記錄。機率不能小於 0 或大於 1，如果這種情況發生在應用程式中，則會擲回例外狀況。

若要向組態註冊取樣器，請考慮下列程式代碼：

builder.Logging.AddRandomProbabilisticSampler(builder.Configuration);

變更執行中應用程式中的取樣規則

隨機概率取樣支援透過介面的 IOptionsMonitor<TOptions> 運行時間組態更新。如果您使用支援重載的設定提供者，例如檔案組態提供者，您可以在運行時間更新取樣規則，而不需重新啟動應用程式。

例如，您可以使用下列 appsettings.json啟動應用程式，這實際上可作為 no-op：

{
  "Logging": {
    "RandomProbabilisticSampler": {
      "Rules": [
        {
          "Probability": 1
        }
      ]
    }
  }
}

當應用程式執行時，您可以使用下列設定來更新 appsettings.json ：

{
  "Logging": {
    "RandomProbabilisticSampler": {
      "Rules": [
        {
          "Probability": 0.01,
          "LogLevel": "Information"
        }
      ]
    }
  }
}

新的規則會自動套用，例如，使用上述設定，會取樣 1% 記錄 LogLevel.Information 。

如何套用取樣規則

演算法與記錄篩選非常類似，但有一些差異。

記錄取樣規則評估會在每個記錄檔記錄上執行，不過，有效能優化，例如快取。下列演算法使用於每個特定類別的記錄檔記錄：

選取等於或高於記錄器記錄層級的規則 LogLevel 。
選取未定義或定義的規則 EventId ，並等於記錄事件識別符。
選取具有最長相符類別前置詞的規則。如果找不到匹配，請選擇所有未指定類別的規則。
如果選取多個規則，請使用最後一個。
如果未選取任何規則，則不會套用抽樣，例如，記錄檔會照常發出。

內嵌程式碼設定

builder.Logging.AddRandomProbabilisticSampler(options =>
{
    options.Rules.Add(
        new RandomProbabilisticSamplerFilterRule(
            probability: 0.05d,
            eventId : 1001));
});

上述組態：

範例 5% 所有類別和層級的事件標識碼為 1001 的記錄。
從其他所有日誌中抽取 100 個% 样本。

簡單機率設定

針對基本案例，您可以設定單一機率值，以套用至指定層級或低於指定層級的所有記錄：

builder.Logging.AddRandomProbabilisticSampler(0.01, LogLevel.Information);
builder.Logging.AddRandomProbabilisticSampler(0.1, LogLevel.Warning);

上述程式碼會註冊取樣器，取樣 10 個% 日誌的 Warning 和 1 個%（及以下級別）的 Information 日誌。如果配置中沒有包含 Information 的規則，那麼會取樣 10% Warning 日誌和以下所有層級，包括 Information。

實作自定義取樣

您可以透過從 LoggingSampler 抽象類衍生並覆寫其抽象成員，來建立自定義取樣策略。這可讓您根據特定需求量身打造取樣行為。例如，自訂取樣器可以：

根據記錄狀態中特定索引鍵/值組的存在和值，進行取樣決策。
套用速率限制邏輯，例如只有在預先定義時間間隔內的記錄數目維持在低於特定閾值時，才會發出記錄。

若要實作自定義取樣器，請遵循下列步驟：

建立繼承自 LoggingSampler的類別。
覆寫 LoggingSampler.ShouldSample 方法來定義您的自定義取樣邏輯。
使用 AddSampler 擴充方法在記錄管線中註冊您的自定義取樣器。

針對未篩選出的每個日誌記錄，LoggingSampler.ShouldSample 方法會被呼叫一次。其傳回值會決定是否應該輸出日誌記錄。

效能考量

記錄取樣的設計目的是要降低儲存成本，但有所取捨的是稍微增加CPU的使用量。如果您的應用程式產生大量儲存成本高昂的日誌，取樣有助於減少這些日誌的數量。適當地設定時，取樣可能會降低儲存成本，而不會遺失診斷事件的關鍵資訊。

如需內建取樣，請參閱效能評定。

使用取樣時機的記錄層級指引

記錄等級	建議
Trace	請勿套用取樣，因為通常您會在生產環境中停用這些日誌。
Debug	請勿套用取樣，因為通常您會在生產環境中停用這些日誌。
Information	請套用取樣
Warning	請考慮套用取樣
Error	不要套用取樣
Critical	不要套用取樣

最佳做法

從較高的取樣率開始，並視需要向下調整。
使用類別型規則以特定元件為目標。
如果您使用分散式追蹤，請考慮實作以追蹤為基礎的取樣。
共同監視取樣規則的有效性。
尋找應用程式的正確平衡—取樣率太低可以降低可觀察性，而速率太高可能會增加成本。

共用方式為