自訂事件和度量的 Application Insights API

警告

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

在您的應用程式中插入幾行程式碼，以了解使用者對它進行的動作或協助診斷問題。 您可以從裝置和桌面應用程式、Web 用戶端以及 Web 伺服器傳送遙測。 使用 Application Insights 核心遙測 API 來傳送自訂的事件和度量，以及您自己的標準遙測版本。 這個 API 與標準 Application Insights 資料收集器所使用的 API 相同。

附註

針對檢測金鑰擷取的支援將在 2025 年 3 月 31 日結束。 檢測金鑰擷取將會繼續運作，但我們不再提供該功能的更新或支援。 轉換至連接字串以利用新功能。

API 摘要

核心 API 是跨所有平台統一的，除了 GetMetric (僅限 .NET) 之類的一些變化形式。

方法	用於
TrackPageView	頁面、畫面、窗格或表單。
TrackEvent	使用者動作和其他事件。 用來追蹤使用者行為，或監視效能。
GetMetric	零和多維度計量、集中設定的彙總 (僅限 C#)。
TrackMetric	效能度量，例如與特定事件不相關的佇列長度。
TrackException	記錄例外狀況以供診斷。 追蹤與其他事件的發生相對位置，並且檢查堆疊追蹤。
TrackRequest	記錄伺服器要求的頻率和持續時間以進行效能分析。
TrackTrace	資源診斷日誌訊息。 您也可以擷取第三方記錄。
TrackDependency	記錄應用程式所依賴之外部元件呼叫的持續時間及頻率。

您可以將屬性和度量附加到大多數遙測呼叫中。

在您開始之前

如果您還沒有 Application Insights SDK 的參考：

• 將 Application Insights SDK 加入至專案：

  • ASP.NET 專案
  • ASP.NET Core 專案
  • Java 專案
  • Node.js 專案
  • 每個網頁中的 JavaScript

• 在裝置或 Web 伺服器程式碼中，加入：

  C#：using Microsoft.ApplicationInsights;

  Visual Basic：Imports Microsoft.ApplicationInsights

  爪哇島：import com.microsoft.applicationinsights.TelemetryClient;

  Node.js：var applicationInsights = require("applicationinsights");

取得 TelemetryClient 執行個體

取得 TelemetryClient 的執行個體 (除非是在網頁的 JavaScript 中)：

針對 ASP.NET Core 應用程式和適用於 .NET/.NET Core 的非 HTTP/背景工作角色應用程式，請從相依性插入容器取得 TelemetryClient 的執行個體，如其各自的文件中所述。

如果您使用 Azure Functions v2+ 或 Azure WebJobs v3+，請參閱監視 Azure Functions。

C#

private TelemetryClient telemetry = new TelemetryClient();

如果您看到指出此方法已過時的訊息，請參閱 microsoft/ApplicationInsights-dotnet#1152 以取得詳細資訊。

Visual Basic

Private Dim telemetry As New TelemetryClient

爪哇島

private TelemetryClient telemetry = new TelemetryClient();

Node.js

var telemetry = applicationInsights.defaultClient;

TelemetryClient 具備執行緒安全。

針對 ASP.NET 和 Java 專案，系統會自動擷取傳入 HTTP 要求。 您可能會希望為應用程式中其他的模組建立更多的 TelemetryClient 實例。 例如，您可以在中介軟體類別中配置一個 TelemetryClient 執行個體，用來報告商業邏輯事件。 您可以設定 UserId 和 DeviceId 等屬性，藉此辨識機器。 這項資訊會附加至執行個體所傳送的所有事件。

C#

TelemetryClient.Context.User.Id = "...";
TelemetryClient.Context.Device.Id = "...";

爪哇島

telemetry.getContext().getUser().setId("...");
telemetry.getContext().getDevice().setId("...");

在 Node.js 專案中，您可以使用 new applicationInsights.TelemetryClient(instrumentationKey?) 建立新的執行個體。 只有在需要從單一 defaultClient 隔離組態的案例中，才建議使用此方法。

TrackEvent

在 Application Insights 中，「自訂事件」是您可以在計量瀏覽器顯示為彙總計數，以及在診斷搜尋中顯示為個別發生點的資料點。 (它與 MVC 或其他架構的「事件」不相關。)

在您的程式碼中插入 TrackEvent 呼叫，以計算各種事件。 例如，您可能想要追蹤使用者選擇特定功能的頻率。 或者，您可能想知道使用者達成特定目標或犯特定錯誤的次數。

例如，在遊戲應用程式中，每當使用者贏得遊戲時傳送事件：

JavaScript

appInsights.trackEvent({name:"WinGame"});

C#

telemetry.TrackEvent("WinGame");

Visual Basic

telemetry.TrackEvent("WinGame")

爪哇島

telemetry.trackEvent("WinGame");

Node.js

telemetry.trackEvent({name: "WinGame"});

記錄分析中的自訂事件

遙測資料可在customEvents或使用體驗的中取得。 事件可能來自 trackEvent(..) 或 Click Analytics 自動收集外掛程式。

如果取樣運作中，itemCount 屬性會顯示大於 1 的值。 例如，itemCount==10 表示在 trackEvent() 的 10 個呼叫中，取樣處理序只會傳輸其中一個。 若要取得正確的自訂事件計數，請使用程式碼，例如 customEvents | summarize sum(itemCount)。

附註

itemCount 的最小值為 1；記錄本身代表一個項目。

GetMetric

若要了解如何有效地使用 GetMetric() 呼叫來擷取 .NET 和 .NET Core 應用程式的本機預先彙總計量，請參閱 .NET 和 .NET Core 中的自訂計量集合。

TrackMetric

附註

Microsoft.ApplicationInsights.TelemetryClient.TrackMetric 不是傳送計量的慣用方法。 您應該一律預先彙總一段時間的計量，再進行傳送。 使用其中一個 GetMetric(..) 多載來取得可供存取 SDK 預先彙總功能的計量物件。

如果您要實作自己的預先彙總邏輯，則可使用 TrackMetric() 方法來傳送所產生的彙總。 如果您的應用程式需要每次傳送個別遙測項目 (未隨時間彙總)，則可能有事件遙測的使用案例。 請參閱 TelemetryClient.TrackEvent(Microsoft.ApplicationInsights.DataContracts.EventTelemetry)。

Application Insights 可以將未附加至特定事件的計量繪製成圖表。 例如，您可以定期監視佇列長度。 當您使用計量時，個別測量的重要性就不如變化和趨勢，因此統計圖表很有用。

若要將計量傳送至 Application Insights，您可以使用 TrackMetric(..) API。 您有兩種方式可以傳送計量：

• 單一值。 每次在應用程式中執行一個測量，都會將對應值傳送至 Application Insights。

  例如，假設您有一個描述容器中項目數的計量。 在特定期間內，您先將 3 個項目放入容器中，再移除 2 個項目。 因此，您會呼叫 TrackMetric 兩次。 首先，您會傳遞值 3，然後傳遞值 -2。 Application Insights 會代替您儲存這兩個值。

• 彙總。 使用計量時，每個單一測量通常並不重要。 相反地，在特定期間內發生的狀況摘要才重要。 這類摘要稱為彙總。

  在前述範例中，該期間的彙總計量總和為 1，而計量值的計數為 2。 使用彙總方法時，您只會在每段期間叫用 TrackMetric 一次，並傳送彙總值。 建議使用此方法，因為該方法可以藉由傳送較少資料點至 Application Insights，同時仍收集所有相關資訊，來大幅降低成本和效能負擔。

單一值範例

若要傳送單一計量值︰

JavaScript

appInsights.trackMetric({name: "queueLength", average: 42});

C#

var sample = new MetricTelemetry();
sample.Name = "queueLength";
sample.Sum = 42.3;
telemetryClient.TrackMetric(sample);

爪哇島

telemetry.trackMetric("queueLength", 42.0);

Node.js

telemetry.trackMetric({name: "queueLength", value: 42.0});

Log Analytics 中的自訂計量

customMetrics的 資料表中有提供遙測資料。 每個資料列各代表應用程式中的一個 trackMetric(..) 呼叫。

• valueSum：測量結果的總和。 若要取得平均值，請將它除以 valueCount。
• valueCount：彙總到這個 trackMetric(..) 呼叫的測量數目。

附註

valueCount 的最小值為 1；記錄本身代表一個項目。

頁面檢視

在裝置或網頁應用程式中，每個畫面或頁面載入時預設會傳送頁面檢視遙測。 但是，您可以變更預設設定，於其他或不同的時間追蹤頁面瀏覽。 例如，在顯示索引標籤或窗格的應用程式中，您可能想要在使用者每次開啟新的窗格時追蹤頁面。

使用者和工作階段資料會與頁面檢視一起做為屬性傳送，當有頁面檢視遙測時，讓使用者與工作階段圖表顯現。

自訂頁面檢視

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

爪哇島

telemetry.trackPageView("GameReviewPage");

如果您在不同的 HTML 網頁內有數個索引標籤，您也可以指定 URL：

appInsights.trackPageView("tab1", "http://fabrikam.com/page1.htm");

計時頁面檢視

根據預設，頁面檢視載入時間是指自瀏覽器發送請求開始到調用瀏覽器頁面載入事件為止所測量的時間。

相對地，您可以選擇以下其中一項：

• 在 trackPageView 呼叫中設定明確的持續時間：appInsights.trackPageView("tab1", null, null, null, durationInMilliseconds);。
• 使用頁面檢視計時呼叫 startTrackPage 和 stopTrackPage。

JavaScript

// To start timing a page:
appInsights.startTrackPage("Page1");

...

// To stop timing and log the page:
appInsights.stopTrackPage("Page1", url, properties, measurements);

做為第一個參數的名稱會將開始和停止呼叫相關聯。 預設為目前的頁面名稱。

產生後顯示在計量瀏覽器中的頁面載入持續時間是衍生自開始和停止呼叫之間的間隔。 取決於您實際計時的間隔。

Log Analytics 中的頁面遙測

在 Log Analytics 中，有兩個資料表顯示瀏覽器作業的資料：

• pageViews：包含 URL 和網頁標題的相關資料。
• browserTimings：包含關於用戶端效能的資料，例如處理傳入資料所花費的時間。

若要了解瀏覽器處理不同頁面所花費的時間：

browserTimings
| summarize avg(networkDuration), avg(processingDuration), avg(totalDuration) by name

若要探索不同瀏覽器的熱門程度：

pageViews
| summarize count() by client_Browser

若要將頁面檢視與 AJAX 呼叫產生關聯，請聯結相依性：

pageViews
| join (dependencies) on operation_Id

追蹤請求

伺服器 SDK 使用 TrackRequest 來記錄 HTTP 要求。

如果您想要在 Web 服務模組未運行的環境中模擬請求，也可以自行呼叫。

建議用來傳送要求遙測的方式是在要求作為作業內容的地方。

作業內容

您可以將遙測項目與作業內容相關聯，以便使它們相互關聯。 標準的要求追蹤模組會針對在處理 HTTP 要求時傳送的例外狀況和其他事件執行此動作。 在搜尋和分析中，您可以使用要求的作業識別碼，輕易地找出任何與要求相關聯的事件。

如需關於相互關聯詳細資訊，請參閱 Application Insights 中的遙測相互關聯。

您以手動方式追蹤遙測時，確保遙測相互關聯最簡單的方式是使用此模式：

C#

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here will use the same operation ID.
    ...
    telemetryClient.TrackTrace(...); // or other Track* calls
    ...

    // Set properties of containing telemetry item--for example:
    operation.Telemetry.ResponseCode = "200";

    // Optional: explicitly send telemetry item:
    telemetryClient.StopOperation(operation);

} // When operation is disposed, telemetry item is sent.

在設定作業內容時，StartOperation 會建立所指定類型的遙測項目。 並會在您處置作業時或明確地呼叫 StopOperation 時傳送遙測項目。 如果您使用 RequestTelemetry 做為遙測類型，則其持續時間會設定為開始與停止之間的時間間隔。

在作業範圍內回報的遙測項目會變成這類作業的「子項目」。 操作環境可以是巢狀結構。

在 [搜尋] 中，會使用作業內容來建立 [相關項目] 清單。

如需有關自訂作業追蹤的詳細資訊，請參閱使用 Application Insights .NET SDK 追蹤自訂作業。

Log Analytics 中的請求

在 Application Insights 分析中，要求會顯示在 requests 資料表中。

如果取樣運作中，itemCount 屬性會顯示大於 1 的值。 例如，itemCount==10 表示在 trackRequest() 的 10 個呼叫中，取樣處理序只會傳輸其中一個。 若要取得依要求名稱分割的正確要求計數和平均持續時間，請使用類似如下的程式碼：

requests
| summarize count = sum(itemCount), avgduration = avg(duration) by name

TrackException

傳送例外狀況至 Application Insights︰

• 以計算數目，以了解問題出現的頻率。
• 以檢查個別出現次數。

報告包含堆疊追蹤。

C#

try
{
    ...
}
catch (Exception ex)
{
    telemetry.TrackException(ex);
}

爪哇島

try {
    ...
} catch (Exception ex) {
    telemetry.trackException(ex);
}

JavaScript

try
{
    ...
}
catch (ex)
{
    appInsights.trackException({exception: ex});
}

Node.js

try
{
    ...
}
catch (ex)
{
    telemetry.trackException({exception: ex});
}

SDK 將自動攔截許多例外狀況，所以您不一定需要明確呼叫 TrackException：

• ASP.NET：撰寫程式碼以攔截例外狀況。
• Java EE：自動攔截例外狀況。
• JavaScript：例外會被自動捕獲。 如果您想要停用自動收集，請在您插入網頁的 JavaScript (Web) SDK 載入器指令碼中新增一行：

({
    instrumentationKey: "your key",
    disableExceptionTracking: true
})

Log Analytics 中的例外狀況

在 Application Insights 分析中，例外狀況會顯示在 exceptions 資料表中。

如果取樣運作中，itemCount 屬性會顯示大於 1 的值。 例如，itemCount==10 表示在 trackException() 的 10 個呼叫中，取樣處理序只會傳輸其中一個。 若要取得依例外狀況類型分割的正確例外狀況計數，請使用類似如下的程式碼：

exceptions
| summarize sum(itemCount) by type

大多數重要堆疊資訊已擷取到不同的變數中，但您可以拉開 details 結構以取得更多資訊。 由於這是動態結構，因此您應該將結果轉換成預期的類型。 例如：

exceptions
| extend method2 = tostring(details[0].parsedStack[1].method)

若要將例外狀況與其相關要求產生關聯，請使用聯結：

exceptions
| join (requests) on operation_Id

TrackTrace

使用 TrackTrace 可協助您藉由將階層連結軌跡傳送至 Application Insights 來診斷問題。 您可以傳送診斷資料區塊，並且在診斷搜尋中檢查。

在 .NET 中，記錄配接器使用此 API 將第三方記錄傳送至入口網站。

在 JAVA 中，Application Insights JAVA 代理程式會自動收集並傳送記錄至入口網站。

C#

telemetry.TrackTrace(message, SeverityLevel.Warning, properties);

爪哇島

telemetry.trackTrace(message, SeverityLevel.Warning, properties);

Node.js

telemetry.trackTrace({
    message: message,
    severity: applicationInsights.Contracts.SeverityLevel.Warning,
    properties: properties
});

用戶端/瀏覽器端 JavaScript

trackTrace({
    message: string,
    properties?: {[string]:string},
    severityLevel?: SeverityLevel
})

記錄診斷事件，例如進入或離開某個方法。

參數	描述
message	診斷資料。 可以比名稱長很多。
properties	字串與字串的對應。 用來在入口網站中篩選例外狀況的其他資料。 預設值為空白。
severityLevel	支援的值：SeverityLevel.ts。

您可以搜尋訊息內容，但是 (不同於屬性值) 您無法在其中進行篩選。

message 上的大小限制比屬性上的限制高得多。 TrackTrace 的優點在於您可以將較長的資料放在訊息中。 例如，您可以在該處編碼 POST 資料。

您也可以將嚴重性層級新增至訊息。 就像其他遙測一樣，您可以新增屬性值以供協助篩選或搜尋不同的追蹤集。 例如：

C#

var telemetry = new Microsoft.ApplicationInsights.TelemetryClient();
telemetry.TrackTrace("Slow database response",
                SeverityLevel.Warning,
                new Dictionary<string,string> { {"database", db.ID} });

爪哇島

Map<String, Integer> properties = new HashMap<>();
properties.put("Database", db.ID);
telemetry.trackTrace("Slow Database response", SeverityLevel.Warning, properties);

在搜尋中，您便可以輕鬆地篩選出與特定資料庫相關且具有特定嚴重性層級的所有訊息。

Log Analytics 中的追蹤

在 Application Insights 分析工具中，TrackTrace 的呼叫會顯示在 traces 資料表中。

如果取樣運作中，itemCount 屬性會顯示大於 1 的值。 例如，itemCount==10 表示在 trackTrace() 的 10 個呼叫中，取樣處理序只會傳輸其中一個。 若要取得正確的追蹤呼叫計數，請使用程式碼，例如 traces | summarize sum(itemCount)。

TrackDependency

您可以使用 TrackDependency 呼叫來追蹤回應時間以及呼叫外部程式碼片段的成功率。 結果會出現在入口網站中的相依性圖表中。 在進行相依性呼叫時，必須新增下列程式碼片段。

附註

針對 .NET 和 .NET Core，您也可以使用 TelemetryClient.StartOperation (延伸模組) 方法，以填滿相互關聯所需的 DependencyTelemetry 屬性，以及其他一些屬性，例如開始時間和持續時間，因此您不需要建立自訂計時器，如下列範例所示。 如需詳細資訊，請參閱使用 Application Insights .NET SDK 追蹤自訂作業中的傳出相依性追蹤一節。

C#

var success = false;
var startTime = DateTime.UtcNow;
var timer = System.Diagnostics.Stopwatch.StartNew();
try
{
    success = dependency.Call();
}
catch(Exception ex)
{
    success = false;
    telemetry.TrackException(ex);
    throw new Exception("Operation went wrong", ex);
}
finally
{
    timer.Stop();
    telemetry.TrackDependency("DependencyType", "myDependency", "myCall", startTime, timer.Elapsed, success);
}

爪哇島

boolean success = false;
Instant startTime = Instant.now();
try {
    success = dependency.call();
}
finally {
    Instant endTime = Instant.now();
    Duration delta = Duration.between(startTime, endTime);
    RemoteDependencyTelemetry dependencyTelemetry = new RemoteDependencyTelemetry("My Dependency", "myCall", delta, success);
    dependencyTelemetry.setTimeStamp(startTime);
    telemetry.trackDependency(dependencyTelemetry);
}

Node.js

var success = false;
var startTime = new Date().getTime();
try
{
    success = dependency.Call();
}
finally
{
    var elapsed = new Date() - startTime;
    telemetry.trackDependency({
        dependencyTypeName: "myDependency",
        name: "myCall",
        duration: elapsed,
        success: success
    });
}

請記住，伺服器 SDK 包含相依性模組，可用來自動探索和追蹤特定相依性呼叫 (例如資料庫和 REST API)。 您必須在伺服器上安裝代理程式才能讓模組正常運作。

在 JAVA 中，許多相依性呼叫都可以使用 Application Insights JAVA 代理程式自動追蹤。

如果您想要追蹤自動化追蹤不會攔截的呼叫，可以使用這個呼叫。

若要在 C# 中關閉標準相依性追蹤模組，請編輯 ApplicationInsights.config 並刪除 DependencyCollector.DependencyTrackingTelemetryModule 的參考。 針對 JAVA，請參閱隱藏特定的自動收集遙測。

Log Analytics 中的相依性

在 Application Insights 分析中，trackDependency 的呼叫會顯示在 dependencies 資料表中。

如果取樣運作中，itemCount 屬性會顯示大於 1 的值。 例如，itemCount==10 表示在 trackDependency() 的 10 個呼叫中，取樣處理序只會傳輸其中一個。 若要取得依目標元件分割的正確相依性計數，請使用類似如下的程式碼：

dependencies
| summarize sum(itemCount) by target

若要將相依性與其相關要求產生關聯，請使用聯結：

dependencies
| join (requests) on operation_Id

排清資料

一般而言，SDK 會以固定間隔 (通常是 30 秒) 傳送資料，或每當緩衝區已滿時 (通常是 500 個項目)。 在某些情況下，您可能會想要排清緩衝區。 例如，如果您要在關閉的應用程式中使用 SDK。

.NET

當您使用 Flush() 時，建議您使用此模式：

telemetry.Flush();
// Allow some time for flushing before shutdown.
System.Threading.Thread.Sleep(5000);

當您使用 FlushAsync() 時，建議您使用此模式：

await telemetryClient.FlushAsync()
// No need to sleep

我們建議在關閉應用程式時，請務必執行排清，以保證遙測數據不會遺失。

爪哇島

telemetry.flush();
//Allow some time for flushing before shutting down
Thread.sleep(5000);

Node.js

telemetry.flush();

此函式對伺服器遙測通道而言是非同步的。

附註

• JAVA 和 JavaScript SDK 會在應用程式關機時自動排清。
• 檢閱自動排清設定：在 可能會導致使用 Application Insights 所檢測的 .NET 應用程式效能降低。 啟用自動排清之後，每次叫用 System.Diagnostics.Trace.Trace* 方法都會導致將個別遙測項目以個別相異 Web 要求的形式傳送至擷取服務。 這可能會導致網頁伺服器上的網路和儲存體耗盡。 為了提升效能，建議您停用 autoflush，同時利用 ServerTelemetryChannel，專為更有效的遙測數據傳輸而設計。

已驗證的使用者

在 Web 應用程式中，預設是透過 Cookie 來識別使用者。 如果使用者使用不同的電腦或瀏覽器存取您的應用程式，或刪除 Cookie 資料，可能會被多次計算。

如果使用者登入您的 app，您可以藉由在瀏覽器程式碼中設定經過驗證的使用者識別碼，來取得更正確的計數：

JavaScript

// Called when my app has identified the user.
function Authenticated(signInId) {
    var validatedId = signInId.replace(/[,;=| ]+/g, "_");
    appInsights.setAuthenticatedUserContext(validatedId);
    ...
}

在 ASP.NET Web MVC 的應用程式中，例如：

剃刀

@if (Request.IsAuthenticated)
{
    <script>
        appInsights.setAuthenticatedUserContext("@User.Identity.Name
            .Replace("\\", "\\\\")"
            .replace(/[,;=| ]+/g, "_"));
    </script>
}

這不需要用到使用者的實際登入名稱。 只需是使用者的唯一識別碼。 其中不能包含空格或任何 ,;=| 字元。

使用者識別碼也會設定於工作階段 Cookie 中，並傳送到伺服器。 如果安裝了伺服器 SDK，則會傳送經過驗證的使用者識別碼以作為用戶端和伺服器遙測的內容屬性一部分。 您可以接著對它進行篩選和搜尋。

如果您的 App 會將使用者群組為帳戶，您也可以傳遞適用於該帳戶的識別碼。 適用相同的字元限制。

appInsights.setAuthenticatedUserContext(validatedId, accountId);

在計量瀏覽器中，您可建立可計算 [已驗證的使用者] 和 [使用者帳戶] 的圖表。

您也可以搜尋具有特定使用者名稱和帳戶的用戶端資料點。

附註

.NET Core SDK 中 ApplicationInsightsServiceOptions 類別中的 EnableAuthenticationTrackingJavaScript 屬性 可簡化將使用者名稱插入為 Application Insights JavaScript SDK 所傳送每個追蹤的驗證識別碼所需的 JavaScript 設定。

當此屬性設定為 true 時，會連同用戶端遙測一起列印 ASP.NET Core 中使用者的使用者名稱。 基於這個理由，不再需要手動新增 appInsights.setAuthenticatedUserContext，因為這個元件已經由 ASP.NET Core 的 SDK 自動插入。 驗證識別碼也會傳送至 .NET Core 中 SDK 將識別並用於任何伺服器端遙測的伺服器，如 JavaScript API 參考中所述。

對於運作方式與 ASP.NET Core MVC 不同的 JavaScript 應用程式（例如單頁應用網頁），您仍然需要手動新增 appInsights.setAuthenticatedUserContext。

使用屬性來篩選、搜尋和分割您的資料

您可以將屬性和測量結果附加至您的事件、度量、頁面檢視、例外狀況和其他的遙測資料。

屬性 是可在使用情況報告中用來篩選遙測的字串值。 例如，如果您的應用程式提供數個遊戲，則您可以將遊戲的名稱附加至每個事件，以了解哪些遊戲較受歡迎。

字串長度限制為 8192 個。 如果您想要傳送大量的資料區塊，請使用訊息參數 TrackTrace。

度量 是可以用圖表方式呈現的數值。 例如，您可能想要查看玩家達到的分數是否逐漸增加。 圖表可以依據隨事件傳送的屬性分割，讓您可以針對不同遊戲取得個別或堆疊圖表。

計量值應大於或等於 0，才能正確顯示。

有一些 屬性、屬性值和度量的數目限制 可供您使用。

JavaScript

appInsights.trackEvent({
  name: 'some event',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

appInsights.trackPageView({
  name: 'some page',
  properties: { // accepts any type
    prop1: 'string',
    prop2: 123.45,
    prop3: { nested: 'objects are okay too' }
  }
});

C#

// Set up some properties and metrics:
var properties = new Dictionary <string, string>
    {{"game", currentGame.Name}, {"difficulty", currentGame.Difficulty}};
var metrics = new Dictionary <string, double>
    {{"Score", currentGame.Score}, {"Opponents", currentGame.OpponentCount}};

// Send the event:
telemetry.TrackEvent("WinGame", properties, metrics);

Node.js

// Set up some properties and metrics:
var properties = {"game": currentGame.Name, "difficulty": currentGame.Difficulty};
var metrics = {"Score": currentGame.Score, "Opponents": currentGame.OpponentCount};

// Send the event:
telemetry.trackEvent({name: "WinGame", properties: properties, measurements: metrics});

Visual Basic

' Set up some properties:
Dim properties = New Dictionary (Of String, String)
properties.Add("game", currentGame.Name)
properties.Add("difficulty", currentGame.Difficulty)

Dim metrics = New Dictionary (Of String, Double)
metrics.Add("Score", currentGame.Score)
metrics.Add("Opponents", currentGame.OpponentCount)

' Send the event:
telemetry.TrackEvent("WinGame", properties, metrics)

爪哇島

Map<String, String> properties = new HashMap<String, String>();
properties.put("game", currentGame.getName());
properties.put("difficulty", currentGame.getDifficulty());

Map<String, Double> metrics = new HashMap<String, Double>();
metrics.put("Score", currentGame.getScore());
metrics.put("Opponents", currentGame.getOpponentCount());

telemetry.trackEvent("WinGame", properties, metrics);

附註

切勿在屬性中記錄個人識別資訊。

設定屬性和度量的替代方式

如果更加方便，您可以收集個別物件中事件的參數：

var event = new EventTelemetry();

event.Name = "WinGame";
event.Metrics["processingTime"] = stopwatch.Elapsed.TotalMilliseconds;
event.Properties["game"] = currentGame.Name;
event.Properties["difficulty"] = currentGame.Difficulty;
event.Metrics["Score"] = currentGame.Score;
event.Metrics["Opponents"] = currentGame.Opponents.Length;

telemetry.TrackEvent(event);

警告

不要重複使用相同的遙測項目執行個體 (此範例中的 event) 來呼叫 Track*() 多次。 此作法可能會導致遙測在不正確的配置下被傳送。

Log Analytics 中的自訂指標和屬性

在 Log Analytics 中，自訂計量和屬性會顯示在每個遙測記錄的 customMeasurements 和 customDimensions 屬性中。

例如，如果您將一個名為 "game" 的屬性新增至您的要求遙測，此查詢將會計算不同 "game" 值出現的次數，並顯示自訂計量 "score" 的平均值：

requests
| summarize sum(itemCount), avg(todouble(customMeasurements.score)) by tostring(customDimensions.game)

請注意：

• 當您從 customDimensions 或 customMeasurements JSON 擷取值時，其中包含動態類型，因此您必須將其轉換為 tostring 或 todouble。
• 考量到取樣的可能性，請使用 sum(itemCount) 而不是 count()。

計時事件

有時候您想要繪製執行某些動作耗費多少時間的圖表。 例如，您可能想要知道使用者在遊戲中思考選項時花費多少時間。 若要取得這項資訊，請使用度量參數。

C#

var stopwatch = System.Diagnostics.Stopwatch.StartNew();

// ... perform the timed action ...

stopwatch.Stop();

var metrics = new Dictionary <string, double>
    {{"processingTime", stopwatch.Elapsed.TotalMilliseconds}};

// Set up some properties:
var properties = new Dictionary <string, string>
    {{"signalSource", currentSignalSource.Name}};

// Send the event:
telemetry.TrackEvent("SignalProcessed", properties, metrics);

爪哇島

long startTime = System.currentTimeMillis();

// Perform timed action

long endTime = System.currentTimeMillis();
Map<String, Double> metrics = new HashMap<>();
metrics.put("ProcessingTime", (double)endTime-startTime);

// Setup some properties
Map<String, String> properties = new HashMap<>();
properties.put("signalSource", currentSignalSource.getName());

// Send the event
telemetry.trackEvent("SignalProcessed", properties, metrics);

自訂遙測資料的預設屬性

如果您想為您撰寫的一些自訂事件設定預設屬性值，可以在 TelemetryClient 執行個體中進行設定。 它們會附加在從該用戶端傳送的每個遙測項目上。

C#

using Microsoft.ApplicationInsights.DataContracts;

var gameTelemetry = new TelemetryClient();
gameTelemetry.Context.GlobalProperties["Game"] = currentGame.Name;
// Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame");

Visual Basic

Dim gameTelemetry = New TelemetryClient()
gameTelemetry.Context.GlobalProperties("Game") = currentGame.Name
' Now all telemetry will automatically be sent with the context property:
gameTelemetry.TrackEvent("WinGame")

爪哇島

import com.microsoft.applicationinsights.TelemetryClient;
import com.microsoft.applicationinsights.TelemetryContext;
...

TelemetryClient gameTelemetry = new TelemetryClient();
TelemetryContext context = gameTelemetry.getContext();
context.getProperties().put("Game", currentGame.Name);

gameTelemetry.TrackEvent("WinGame");

Node.js

var gameTelemetry = new applicationInsights.TelemetryClient();
gameTelemetry.commonProperties["Game"] = currentGame.Name;

gameTelemetry.TrackEvent({name: "WinGame"});

單個遙測呼叫可以覆蓋其屬性字典中的預設值。

針對 JavaScript Web 用戶端，請使用 JavaScript 的遙測初始化器。

若要將屬性新增至所有遙測，並包括來自標準集合模組的資料，請實作 ITelemetryInitializer。

取樣、篩選和處理遙測數據

請參閱在 Application Insights SDK 中篩選及前置處理遙測。

停用遙測

動態停止和開始 收集及傳輸遙測資料：

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

爪哇島

telemetry.getConfiguration().setTrackingDisabled(true);

若要停用選取的標準收集器 (例如效能計數器、HTTP 要求或相依性)，請刪除或註解化 ApplicationInsights.config 中的相關行。例如，如果您想要傳送自己的 TrackRequest 資料。

Node.js

telemetry.config.disableAppInsights = true;

若要在初始化時停用選取的標準收集器(例如，效能計數器、HTTP 要求或相依性)，請將設定方法鏈結至您的 SDK 初始化程式碼。

applicationInsights.setup()
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    .setAutoCollectConsole(false)
    .start();

若要在初始化之後停用這些收集器，請使用 Configuration 物件：applicationInsights.Configuration.setAutoCollectRequests(false)。

開發人員模式

偵錯期間，讓您的遙測透過管線加速很有用，如此您就可以立即看到結果。 您也會取得其他訊息，協助您追蹤任何遙測問題。 在生產環境中請將其關閉，因為可能會拖慢您的應用程式。

C#

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

Visual Basic

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = True

Node.js

針對 Node.js，您可以透過 setInternalLogging 啟用內部記錄，並將 maxBatchSize 設定為 0 來啟用開發人員模式，這會在收集遙測時立即傳送遙測。

applicationInsights.setup("ikey")
  .setInternalLogging(true, true)
  .start()
applicationInsights.defaultClient.config.maxBatchSize = 0;

設定已選取自訂遙測的檢測金鑰

C#

var telemetry = new TelemetryClient();
telemetry.InstrumentationKey = "---my key---";
// ...

動態檢測金鑰

若要避免混合來自開發、測試和實際執行環境的遙測，您可以建立個別的 Application Insights 資源，並且依據環境變更其金鑰。

而不是從組態檔取得檢測金鑰，您可以在程式碼中設定。 在初始化方法中設定金鑰，例如 ASP.NET 服務中的 global.aspx.cs：

C#

protected void Application_Start()
{
    Microsoft.ApplicationInsights.Extensibility.
    TelemetryConfiguration.Active.InstrumentationKey =
        // - for example -
        WebConfigurationManager.Settings["ikey"];
    ...
}

JavaScript

appInsights.config.instrumentationKey = myKey;

在網頁中，您可能想要從 web 伺服器的狀態中設定，而不是將其直接編碼到指令碼中。 例如，在 ASP.NET 應用程式中產生的網頁：

Razor 中的 JavaScript

<script type="text/javascript">
// Standard Application Insights webpage script:
var appInsights = window.appInsights || function(config){ ...
// Modify this part:
}({instrumentationKey:
    // Generate from server property:
    @Microsoft.ApplicationInsights.Extensibility.
        TelemetryConfiguration.Active.InstrumentationKey;
}) // ...

    String instrumentationKey = "00000000-0000-0000-0000-000000000000";

    if (instrumentationKey != null)
    {
        TelemetryConfiguration.getActive().setInstrumentationKey(instrumentationKey);
    }

遙測上下文

TelemetryClient 具有內容屬性，其中包含與所有遙測資料一起傳送的值。 這些值通常由標準遙測模組設定，但是您也可以自行設定。 例如：

telemetry.Context.Operation.Name = "MyOperationName";

如果您自行設定這些值，請考慮從 ApplicationInsights.config 移除相關的程式碼行，讓您的值和標準值不致混淆。

• 元件：應用程式及其版本。
• 裝置︰應用程式執行所在裝置的相關資料 在 Web 應用程式中，這是傳送遙測的伺服器或用戶端裝置。
• InstrumentationKey：Azure 中遙測顯示位置的 Application Insights 資源。 通常會從 ApplicationInsights.config 取得。
• 位置：裝置的地理位置。
• 操作：在 Web 應用程式中，目前的 HTTP 要求。 在其他應用程式類型中，您可以設定此值將事件分組在一起。
  • 識別碼：產生的值，與不同事件相互關聯，如此當您在診斷搜尋中檢查任何事件時，您可以發現相關項目。
  • 名稱：識別碼，通常是 HTTP 要求的 URL。
  • SyntheticSource：如果不為 null 或空白，這個字串表示要求的來源已被識別為傀儡程式或 Web 測試。 根據預設，會從計量瀏覽器的計算中排除。
• 會話︰使用者的會話。 識別碼會被設為新產生的值，當使用者一段時間未活躍時會變更。
• 使用者：使用者資訊。

限制

每個應用程式 (亦即每個檢測金鑰) 都有一些計量和事件的數目限制。 限制取決於您選擇的定價方案。

資源	預設限制	上限	備註
每日資料總量	100 GB	請連絡支援人員。	您可以設定上限以減少資料。 如果您需要更多資料，可以從入口網站將限制增加到最多 1,000 GB。 若容量大於 1000 GB，請傳送電子郵件給 AIDataCap@microsoft.com。
節流	32,000 個事件/秒	請連絡支援人員。	此限制會測量超過一分鐘。
數據保存日誌	30 到 730 天	730 天	此資源適用於日誌。
資料保留計量	90 天	90 天	此資源適用於計量瀏覽器。
可用性多步驟測試詳述的結果保留期	90 天	90 天	此資源會提供每個步驟的詳細結果。
遙測項目大小上限	64 KB	64 KB
每個批次的遙測項目數上限	64,000	64,000
屬性和度量名稱長度	150	150	請參閱類型結構描述。
屬性值字串長度	8,192	8,192	請參閱類型結構描述。
追蹤和例外狀況訊息長度	32,768	32,768	請參閱類型結構描述。
每個 Application Insights 資源的可用性測試計數	100	100
每個資源群組的可用性測試計數	800	800	請參閱 Azure Resource Manager
可用性測試中每個測試的重新導向數上限	10	10
可用性測試的最低測試頻率	300 秒		自訂的測試頻率或低於 5 分鐘的頻率，需要自訂 TrackAvailability 的實現。
.NET Profiler 和 快照偵錯器 數據保留	兩週	請連絡支援人員。 資料保留上限為六個月。
每天傳送的 .NET Profiler 數據	無限制	沒有限制。
每天傳送的快照調試器數據	每個受監視應用程式每天 30 個快照集	沒有限制。	可透過設定修改每個應用程式所收集的快照集數目。

如需有關定價和配額的詳細資訊，請參閱 Application Insights 計費。

若要避免達到資料速率限制，請使用取樣。

若要決定資料的保留時間，請參閱資料保留和隱私權。

參考文件

• .NET 參考
• Java 參考
• JavaScript 參考

SDK 程式碼

• .NET
• Windows Server 套件
• Java SDK
• Node.js SDK
• JavaScript SDK

下一步

• 若要檢閱常見問題 （FAQ），請參閱 Application Insights API 中的自定義事件和計量常見問題
• 搜尋事件和記錄