自訂事件和計量的 Application Insights API

在您的應用程式中插入幾行程式碼，以瞭解使用者正在執行哪些動作，或協助診斷問題。 您可以從裝置和傳統型應用程式、Web 用戶端和網頁伺服器傳送遙測。 使用 Application Insights 核心遙測 API 來傳送自訂事件和計量，以及您自己的標準遙測版本。 此 API 與標準 Application Insights 資料收集器所使用的 API 相同。

注意

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

API 摘要

核心 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

• 在您的裝置或網頁伺服器程式碼中，包括：

  C#：using Microsoft.ApplicationInsights;

  Visual Basic:Imports Microsoft.ApplicationInsights

  Java：import com.microsoft.applicationinsights.TelemetryClient;

  Node.jsvar 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 實例來報告商務邏輯事件。 您可以設定 和 DeviceId 等 UserId 屬性來識別電腦。 此資訊會附加至實例傳送的所有事件。

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

Log Analytics 中的自訂事件

遙測可在 Application Insights 記錄索引標籤 或使用體驗 的資料表中 customEvents 取得。 事件可能來自 trackEvent(..) 或 Click Analytics 自動收集外掛程式 。

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

注意

itemCount 的最小值為一;記錄本身代表專案。

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。

  例如，假設您有一個計量來描述容器中的專案數目。 在特定時段內，您會先將三個專案放入容器中，然後移除兩個專案。 因此，你會呼叫 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 Analytics 的 資料表中 customMetrics 取得。 每個資料列都代表應用程式中的 trackMetric(..) 呼叫。

• valueSum：度量的總和。 若要取得平均值，請除以 valueCount 。
• valueCount：匯總至此 trackMetric(..) 呼叫的度量數目。

注意

valueCount 的最小值為一;記錄本身代表專案。

頁面檢視

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

使用者和會話資料會隨著頁面檢視一起傳送為屬性，因此當有頁面檢視遙測時，使用者和會話圖表就會運作。

自訂頁面檢視

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 ：會自動攔截例外狀況。 如果您想要停用自動收集，請將一行新增至您在網頁中插入的 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);

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 相互關聯所需的屬性和一些其他屬性的 （extension） 方法，例如開始時間和持續時間，因此您不需要建立自訂計時器，如下列範例所示。 如需詳細資訊，請參閱使用 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 來識別。 如果使用者從不同的電腦或瀏覽器存取您的應用程式，或刪除 Cookie，可能會多次計算使用者。

如果使用者登入您的應用程式，您可以在瀏覽器程式碼中設定已驗證的使用者識別碼，以取得更精確的計數：

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，則驗證的使用者識別碼會作為用戶端和伺服器遙測內容屬性的一部分傳送。 然後，您可以篩選並搜尋它。

如果您的應用程式將使用者分組為帳戶，您也可以傳遞帳戶的識別碼。 套用相同的字元限制。

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 。

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

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

屬性 是字串值，可用來在使用量報告中篩選遙測。 例如，如果您的 app 提供數個遊戲，您可以將遊戲的名稱附加至每個事件，讓您可以看到哪些遊戲更受歡迎。

字串長度的限制為 8,192。 如果您想要傳送大量資料，請使用 的 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 。

範例、篩選和處理遙測

請參閱 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 ，並將 設定為 0maxBatchSize ，這會導致在收集遙測時立即傳送遙測。

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

設定所選自訂遙測的檢測金鑰

C#

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

動態檢測金鑰

若要避免從開發、測試和生產環境混合遙測，您可以 建立個別的 Application Insights 資源 ，並根據環境變更其金鑰。

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

C#

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

JavaScript

appInsights.config.instrumentationKey = myKey;

在網頁中，您可能會想要從網頁伺服器的狀態設定它，而不是將它字面編碼到腳本中。 例如，在 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 具有 CoNtext 屬性，其中包含隨所有遙測資料一起傳送的值。 它們通常是由標準遙測模組所設定，但您也可以自行設定它們。 例如：

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。 針對大於 1,000 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

常見問題集

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

為什麼我遺漏遙測資料？

如果應用程式關閉之前未排清，這兩 個 TelemetryChannels 將會遺失緩衝的遙測。

若要避免資料遺失，請在應用程式關閉時清除 TelemetryClient。

如需詳細資訊，請參閱 排清資料 。

可能會 Track_() 擲回哪些例外狀況？

無。 您不需要將它們包裝在 try-catch 子句中。 如果 SDK 遇到問題，它會在偵錯主控台輸出中記錄訊息，並在診斷搜尋中通過訊息。

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

是， 資料存取 API 。 如果您已 移轉至以工作區為基礎的資源 ，或 如果您仍在傳統資源上， 則擷取資料的其他方式包括 Power BI 。

為何會忽略對自訂事件和計量 API 的呼叫？

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

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

為什麼搜尋和計量圖表中的計數不相等？

取樣 可減少從您的應用程式傳送至入口網站的遙測專案數目（例如要求和自訂事件）。 在 [搜尋] 中，您會看到收到的專案數目。 在顯示事件計數的計量圖表中，您會看到發生的原始事件數目。

傳輸的每個專案都會 itemCount 攜帶屬性，以顯示專案所代表的原始事件數目。 若要觀察作業中的取樣，您可以在 Log Analytics 中執行此查詢：

    requests | summarize original_events = sum(itemCount), transmitted_events = count()

如何設定事件的警示？

Azure 警示僅適用于計量。 建立自訂計量，以在事件發生時跨越值臨界值。 然後設定計量的警示。 每當計量跨越任一方向的臨界值時，您就會收到通知。 不論初始值是高還是低，您都不會收到通知， 直到第一次交叉為止。 一律會有幾分鐘的延遲。

下一步

• 搜尋事件和記錄