自訂事件和度量的 Application Insights API

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

注意

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

API summary

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

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

您可以 附加屬性和度量 至這裡大部分的遙測呼叫。

在您開始使用 Intune 之前

如果您還沒有 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

  Java：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

Java

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 = "...";

Java

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")

Java

telemetry.trackEvent("WinGame");

Node.js

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

記錄分析中的自訂事件

遙測可在 Application Insights 記錄索引標籤或使用體驗的資料表 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);

Java

telemetry.trackMetric("queueLength", 42.0);

Node.js

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

Log Analytics 中的自訂計量

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

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

注意

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

網頁檢視

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

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

自訂頁面檢視

JavaScript

appInsights.trackPageView("tab1");

C#

telemetry.TrackPageView("GameReviewPage");

Visual Basic

telemetry.TrackPageView("GameReviewPage")

Java

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

TrackRequest

伺服器 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);
}

Java

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：自動攔截例外狀況。 如果您想要停用自動收集，請在您插入網頁的程式碼片段中加入一行：

({
    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);

Java

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} });

Java

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);
}

Java

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

建議您一律將排清作為應用程式關機的一部分，以確保遙測不會遺失。

Java

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

Node.js

telemetry.flush();

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

注意

JAVA 和 JavaScript SDK 會在應用程式關機時自動排清。

驗證的使用者

在 Web 應用程式中，預設是透過 Cookie 來識別使用者。 如果使用者從不同的電腦或瀏覽器存取您的 app 或刪除 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 應用程式，例如：

Razor

@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，因為 SDK 已插入 ASP.NET Core。 驗證識別碼也會傳送至 .NET Core 中 SDK 將識別並用於任何伺服器端遙測的伺服器，如 JavaScript API 參考中所述。

對於與 ASP.NET Core MVC 相同的 JavaScript 應用程式 (例如 SPA Web 應用程式)，您仍然需要手動新增 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)

Java

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);

Java

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")

Java

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。

範例、篩選和處理遙測

您可以撰寫程式碼，在從 SDK 傳送遙測資料前加以處理。 處理包括從標準遙測模組 (如 HTTP 要求收集和相依性收集) 的資料。

實作 ITelemetryInitializer 以屬性至遙測資料。 例如，您可以新增版本號碼或從其他屬性計算得出的值。

篩選可以先修改或捨棄遙測，再藉由實作 ITelemetryProcessor 從 SDK 傳送遙測。 您可控制要傳送或捨棄的項目，但是您必須考量這對您的度量的影響。 視您捨棄項目的方式而定，您可能會喪失在相關項目之間瀏覽的能力。

取樣是減少從應用程式傳送至入口網站的資料量的套件方案。 它在這麼做時並不會影響顯示的度量。 而且在這麼做時，不會影響您在相關項目 (如例外狀況、要求和頁面檢視) 之間瀏覽，進而診斷問題的能力。

若要深入了解，請參閱在 Application Insights SDK 中篩選及前置處理遙測。

停用遙測

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

C#

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

Java

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);
    }

TelemetryContext

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	請參閱類型結構描述。
每個應用程式的可用性測試計數	100	100
分析工具和快照集資料保留	兩週	請連絡支援人員。 資料保留上限為六個月。
每天傳送的分析工具資料	沒有限制	沒有限制
每天傳送的快照集資料	每個受監視應用程式每天 30 個快照集	沒有限制	可透過設定修改每個應用程式所收集的快照集數目。

如需詳細資訊，請參閱 Application Insights 帳單。

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

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

參考文件

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

SDK 程式碼

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

常見問題集

為什麼我的遙測資料遺失了？

若在應用程式關閉之前未清除，兩個遙測通道都將遺失緩衝遙測。

為了避免資料遺失，請在應用程式關閉時清除遙測用戶端。

如需更多資訊，請參閱清除資料。

Track_() 呼叫會擲回什麼例外狀況？

無。 您不需要將它們包裝在 try-catch 子句中。 如果 SDK 發生問題，它會在偵錯主控台輸出以及 (若訊息得以傳輸過去) 診斷搜尋中記錄訊息。

是否有 REST API 可供從入口網站中取得資料？

是，資料存取 API。 其他擷取資料的方式包含 Power BI (若您已遷移至工作區型資源) 或連續匯出 (若您仍使用傳統資源)。

為什麼我對自訂事件和計量 API 的呼叫遭到忽略？

Application Insights SDK 與自動檢測不相容。 如果已啟用自動檢測，將會忽略對 Track() 以及其他自訂事件和計量 API 的呼叫。

在 App Service 頁面的 Application Insights 索引標籤上，關閉 Azure 入口網站中的自動檢測，或將 ApplicationInsightsAgent_EXTENSION_VERSION 設定為 disabled。

下一步

• 搜尋事件和記錄
• 疑難排解