共用方式為

Application Insights 中的遙測通道

  • 發行項

遙測通道是 Application Insights SDK 不可或缺的一部分。 遙測通道管理遙測的緩衝處理和到 Application Insights 服務的傳輸。 SDK 的 .NET 和 .NET Core 版本有兩個內建遙測通道：InMemoryChannel 和 ServerTelemetryChannel。 本文詳細說明每個通道並示範如何自訂通道行為。

警告

我們建議為新應用程式或客戶提供 Azure 監視器 Application Insights 的 Azure 監視器 OpenTelemetry 散發版本。 Azure 監視器 OpenTelemetry 散發版本提供與 Application Insights SDK 類似的功能和體驗。 您可以使用適用於 .NET、Node.js 和 Python 的移轉指南，從 Application Insights SDK 移轉，但我們仍在努力新增更多功能以提供回溯相容性。

什麼是遙測通道？

遙測通道負責緩衝處理遙測項目，並將其傳送至 Application Insights 服務儲存，以便進行查詢和分析。 遙測通道是任何可實作 Microsoft.ApplicationInsights.ITelemetryChannel 介面的類別。

呼叫過所有遙測初始設定式和遙測處理器之後，便會呼叫遙測通道的 Send(ITelemetry item) 方法。 因此，遙測處理器卸除的任何項目都不會觸達通道。 Send() 方法通常不會立即將項目傳送至後端。 一般而言，會在記憶體中緩衝處理再批次傳送這些項目，以便提升傳輸的效率。

即時計量資料流也有自訂通道，可支援遙測的即時串流。 此通道與一般遙測通道無關，本文件亦未套用此通道。

內建遙測通道

Application Insights .NET 和 .NET Core SDK 隨附兩個內建通道：

  • InMemoryChannel：輕量型通道，會緩衝記憶體中的項目，直到傳送為止。 項目會在記憶體中緩衝處理，並每隔 30 秒或緩衝對象達 500 個項目時排清一次。 此通道提供最低可靠性保證，因其不會在失敗後重新嘗試傳送遙測。 此通道也不會將項目保留在磁碟上。 因此未傳送的項目會於應用程式關閉時永久遺失，無論應用程式是正常或不正常關閉。 此通道會實作 Flush() 方法，可用以同步強制排清任何記憶體內部的遙測項目。 此通道非常適合需要同步排清的短期執行應用程式。

    此通道屬於較大 Microsoft.ApplicationInsights NuGet 套件的一部分，也是 SDK 在未設定其他任何項目時使用的預設通道。

  • ServerTelemetryChannel：更進階的通道，具有重試原則，且可將資料儲存在本地磁碟。 如果發生暫時性錯誤，此通道會重新嘗試傳送遙測。 此通道也會使用本地磁碟儲存體，在網路中斷或高遙測磁碟區期間將項目保留在磁碟上。 因為有這些重試機制和本地磁碟儲存體，一般認為此通道更為可靠。 建議將此通道用於所有實際案例。 根據官方文件設定，ASP.NET 和 ASP.NET Core 應用程式預設使用此通道。 此通道已針對具有長時間執行流程的伺服器情節進行最佳化。 此通道實作的 Flush() 方法並非同步。

    此通道隨附為 Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel NuGet 套件，只要您使用 Microsoft.ApplicationInsights.Web 或 Microsoft.ApplicationInsights.AspNetCore NuGet 套件便會自動取得。

設定遙測通道

您可以將遙測通道設定為作用中的遙測設定，藉此設定遙測通道。 若是 ASP.NET 應用程式，設定包括將遙測通道執行個體設定為 TelemetryConfiguration.Active，或是透過 ApplicationInsights.config 進行修改。 若是 ASP.NET Core 應用程式，設定包括將通道新增至相依性插入容器。

下列各節顯示各種應用程式型別通道的 StorageFolder 設定範例。 StorageFolder 只是其中一個可供設定的項目。 如需設定的完整清單，請參閱本文稍後的通道中可設定的設定值一節。

使用 ApplicationInsights.config 設定 ASP.NET 應用程式

ApplicationInsights.config 的下一節顯示已由 StorageFolder 設定為自訂位置的 ServerTelemetryChannel 通道：

    <TelemetrySinks>
        <Add Name="default">
            <TelemetryProcessors>
                <!-- Telemetry processors omitted for brevity  -->
            </TelemetryProcessors>
            <TelemetryChannel Type="Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel.ServerTelemetryChannel, Microsoft.AI.ServerTelemetryChannel">
                <StorageFolder>d:\temp\applicationinsights</StorageFolder>
            </TelemetryChannel>
        </Add>
    </TelemetrySinks>

ASP.NET 應用程式的程式碼設定

下列程式碼設定 ServerTelemetryChannel 執行個體，將 StorageFolder 設定為自訂位置。 在應用程式開頭新增此程式碼，通常是在 Global.aspx.cs 中的 Application_Start() 方法中。

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;
protected void Application_Start()
{
    var serverTelemetryChannel = new ServerTelemetryChannel();
    serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
    serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
    TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;
}

ASP.NET Core 應用程式的程式碼設定

修改 Startup.cs 類別的 ConfigureServices 方法，如下所示：

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.WindowsServer.TelemetryChannel;

public void ConfigureServices(IServiceCollection services)
{
    // This sets up ServerTelemetryChannel with StorageFolder set to a custom location.
    services.AddSingleton(typeof(ITelemetryChannel), new ServerTelemetryChannel() {StorageFolder = @"d:\temp\applicationinsights" });

    services.AddApplicationInsightsTelemetry();
}

重要

ASP.NET Core 應用程式不支援使用 TelemetryConfiguration.Active 設定通道。

.NET/.NET Core 主控台應用程式的程式碼設定

針對主控台應用程式，.NET 和 .NET Core 的程式碼相同：

var serverTelemetryChannel = new ServerTelemetryChannel();
serverTelemetryChannel.StorageFolder = @"d:\temp\applicationinsights";
serverTelemetryChannel.Initialize(TelemetryConfiguration.Active);
TelemetryConfiguration.Active.TelemetryChannel = serverTelemetryChannel;

ServerTelemetryChannel 的操作詳細資料

ServerTelemetryChannel 會將抵達的項目儲存在記憶體內部緩衝區中。 每 30 秒或緩衝對象達 500 個項目時，即會對項目進行序列化、壓縮並儲存到 Transmission 執行個體。 單一 Transmission 執行個體最多包含 500 個項目，代表透過單一 HTTPS 呼叫傳送至 Application Insights 服務的遙測批次。

根據預設，最多可以平行傳送 10 個 Transmission 執行個體。 如果遙測抵達速度較快，或者網路或 Application Insights 後端速度緩慢，則 Transmission 執行個體會儲存在記憶體中。 此記憶體內部 Transmission 緩衝區的預設容量為 5 MB。 超過記憶體內部容量時，Transmission 執行個體會儲存在本地磁碟上，上限為 50 MB。

Transmission 執行個體也會在發生網路問題時儲存在本地磁碟上。 只有儲存在本地磁碟上的項目才能在應用程式損毀時存留下來。 只要重新啟動應用程式，即會傳送這些項目。 如果網路問題持續發生，則 ServerTelemetryChannel 會使用介於 10 秒到 1 小時的指數輪詢邏輯，然後再次重新嘗試傳送遙測資料。

通道中可設定的設定值

如需每個通道可設定設定值的完整清單，請參閱：

下列是最常用於 ServerTelemetryChannel 的設定：

  • MaxTransmissionBufferCapacity：通道用來緩衝記憶體傳輸的最大記憶體數量，以位元組為單位。 觸達此容量後，新項目會直接儲存至本地磁碟。 預設值是 5 MB。 設定較高的值會導致磁碟使用量降低，但請記住，如果應用程式損毀，記憶體中的項目將會遺失。
  • MaxTransmissionSenderCapacity：將同時傳送至 Application Insights 的 Transmission 執行個體數目上限。 預設值為 10。 此設定可以設定為較高的數字，建議於產生大量遙測時使用。 大量遙測通常會於負載測試期間或關閉取樣時產生。
  • StorageFolder：通道用來視需要將項目儲存至磁碟的資料夾。 在 Windows 中，如未明確指定其他路徑，則會使用 %LOCALAPPDATA% 或 %TEMP%。 若是在 Windows 以外的環境，您必須指定有效的位置，否則遙測不會儲存到本地磁碟。

我該使用哪一個通道？

建議將 ServerTelemetryChannel 用於涉及長時間執行應用程式的多數實際案例。 ServerTelemetryChannel 實作的 Flush() 方法非同步。 而且也不保證從記憶體或磁碟傳送所有擱置中的項目。

如果您使用此通道的案例是應用程式即將關閉的案例，建議您在呼叫 Flush() 後引進一些延遲。 所需的確切延遲量難以預測， 相關因素包括：記憶體或磁碟中的項目或 Transmission 執行個體數目、傳輸至後端的項目或執行個體數目，以及通道是否處於指數輪詢情節中。

如果您必須執行同步排清，請使用 InMemoryChannel。

常見問題集

本節提供常見問題的答案。

Application Insights 通道是否保證遙測傳遞？ 若否，哪些情節可能遺失遙測？

簡單來說，沒有任何內建通道能提供遙測傳遞至後端的交易型別保證。 相較於 InMemoryChannel，ServerTelemetryChannel 的傳遞過程更為可靠，但也僅會盡最大努力嘗試傳送遙測。 遙測仍可能在多種情況下遺失，包括下列常見情節：

  • 應用程式損毀時，記憶體中的項目就會遺失。
  • 遙測會在網路問題延長期間遺失。 網路中斷期間或 Application Insights 後端發生問題時，系統會將遙測儲存到本地磁碟。 不過，超過 48 小時的項目會遭捨棄。
  • Windows 中儲存遙測的預設磁碟位置為 %LOCALAPPDATA% 或 %TEMP%。 這些位置通常是機器的本地位置。 如果應用程式實際從某個位置遷移到另一個位置，則儲存在原始位置的遙測就會遺失。
  • 在 Windows 上的 Azure Web Apps 中，預設的磁碟儲存體位置為 D:\local\LocalAppData。 此位置不會保存。 應用程式重新啟動、擴增或進行其他類似作業後即會抹除，導致儲存其中的遙測資料全數遺失。 您可以覆寫預設值，將儲存體指定為可供保存的位置，例如 D:\home。 不過，這類可供保存的位置是由遠端儲存體提供，因此速度可能較為緩慢。

雖然機率較低，但通道也可能造成重複的遙測項目。 當 ServerTelemetryChannel 因網路失敗或逾時而重試、遙測實際傳遞至後端，但因網路問題或逾時而遺失回應時，就會發生此行為。

ServerTelemetryChannel 是否能在 Windows 以外的系統上運作？

雖然其套件和命名空間名稱包含「WindowsServer」，Windows 以外的系統仍支援此通道，但有下列例外狀況。 在 Windows 以外的系統上，通道預設不會建立本地儲存體資料夾。 您必須建立本地儲存體資料夾，並設定通道來使用。 設定本地儲存體之後，通道在所有系統上的運作方式都相同。

注意

使用 2.15.0-beta3 版和更新版本時，現在會為 Linux、Mac 和 Windows 自動建立本機儲存體。 針對非 Windows 系統，SDK 會根據下列邏輯自動建立本機儲存體資料夾：

  • ${TMPDIR}：如果已設定 ${TMPDIR} 環境變數，則會使用此位置。
  • /var/tmp：如果前一個位置不存在，我們會嘗試使用 /var/tmp。
  • /tmp：如果前兩個位置都不存在，我們會嘗試使用 tmp。
  • 如果這些位置都不存在，就不會建立本機儲存體，而仍需要手動設定。 如需完整的實作詳細資料，請參閱此 GitHub 存放庫。

SDK 是否會建立暫存本機儲存體？ 資料是否會在儲存體加密？

SDK 會在網路問題或節流期間，將遙測項目儲存在本地儲存體中。 此資料不會在本地加密。

若是 Windows 系統，SDK 會自動在 %TEMP% 或 %LOCALAPPDATA% 目錄中建立暫存本地資料夾，並限制只有管理員和目前使用者擁有存取權。

若是 Windows 以外的系統，SDK 不會自動建立任何本地儲存體，因此預設不會在本地儲存任何資料。

注意

使用 2.15.0-beta3 版和更新版本時，現在會為 Linux、Mac 和 Windows 自動建立本機儲存體。

您可以自行建立儲存體目錄，並設定通道來使用。 在此情況下，您必須負責確保目錄受到保護。 深入了解資料保護和隱私權。

開放原始碼 SDK

通道為開放原始碼，跟每個適用於 Application Insights 的 SDK 一樣。 在官方 GitHub 存放庫 (英文) 閱讀並參與程式碼或回報問題。

下一步