你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

用于处理自定义事件和指标的 Application Insights API

在应用程序中插入几行代码，即可了解用户在该应用程序中执行的操作或帮助诊断问题。 可以从设备和桌面应用、Web 客户端和 Web 服务器发送遥测数据。 使用 核心遥测 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

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

Log Analytics 中的自定义事件

“Application Insights 日志”选项卡或使用体验上的 customEvents 表中提供了遥测。 事件可能来自 trackEvent(..) 或分析自动收集插件。

如果正在进行采样，那么 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 Analytics 的 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 请求时发送的异常和其他事件执行此操作。 在搜索和分析中，可以使用操作 ID 轻松找到与请求关联的任何事件。

有关关联的详细信息，请参阅 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 Analytics 中，请求出现在 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 Analytics 中，异常出现在 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 Analytics 中，对 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 Analytics 中，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.config 文件中启用自动刷新会导致使用 Application Insights 检测的 .NET 应用程序出现性能下降。 启用自动舒心后，每次调用 System.Diagnostics.Trace.Trace* 方法都会将单个遥测项作为单独的不同 Web 请求发送到引入服务。 这可能会导致 Web 服务器上的网络和存储耗尽。 为了增强性能，建议禁用自动刷新，同时利用旨在实现更有效的遥测数据传输的 ServerTelemetryChannel。

经过身份验证的用户

在 Web 应用中，默认按 Cookie 标识用户。 如果用户从不同的计算机或浏览器访问应用或删除 Cookie，则可能会多次统计它们。

如果用户登录到应用，可以通过在浏览器代码中设置经过身份验证的用户 ID 来获取更准确的计数：

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

不需要使用用户的实际登录名。 只需使用该用户的唯一 ID 即可。 该 ID 不能包含空格或任何 ,;=| 字符。

还可在会话 Cookie 中设置用户 ID 并将其发送到服务器。 如果安装了服务器 SDK，则经过身份验证的用户 ID 将作为客户端和服务器遥测上下文属性的一部分发送。 可对其进行筛选和搜索。

如果应用将用户分组到各个帐户，则还可以传递帐户的标识符。 适用相同的字符限制。

appInsights.setAuthenticatedUserContext(validatedId, accountId);

在指标资源管理器中，可以创建统计“经身份验证的用户”和“用户帐户”的图表。

还可以搜索具有特定用户名和帐户的客户端数据点。

注意

.NET Core SDK 的 ApplicationInsightsServiceOptions 类中的 EnableAuthenticationTrackingJavaScript 属性简化了将 Application Insights JavaScript SDK 发送的每个跟踪的用户名作为授权 ID 注入所需的 JavaScript 配置。

当此属性设置为 true 时，ASP.NET Core 中用户的用户名将与客户端遥测一起打印。 因此，不再需要手动添加 appInsights.setAuthenticatedUserContext，因为它已由 SDK for ASP.NET Core 注入。 授权 ID 也会发送到服务器，.NET Core 中的 SDK 会在其中识别它，并将其用于任何服务器端遥测，如 JavaScript API 参考所述。

但是，对于工作方式不同于 ASP.NET Core MVC 的 JavaScript 应用程序（例如 SPA Web 应用），你仍然需要手动添加 appInsights.setAuthenticatedUserContext。

使用属性对数据进行筛选、搜索和分段

可以将属性和度量附加到事件、指标、页面视图、异常和其他遥测数据。

属性是可以在使用情况报告中用来筛选遥测数据的字符串值。 例如，如果应用提供多种游戏，可以将游戏的名称附加到每个事件，了解哪些游戏更受欢迎。

字符串长度限制为 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 中的自定义度量和属性

在 中，自定义指标和属性显示在每个遥测记录的 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();

要在初始化后禁用这些收集器，请使用配置对象：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 中删除相关的代码行，以便值与标准值不会造成混淆。

• Component：应用及其版本。
• Device：有关正在运行应用的设备的数据。 在 Web 应用中，是指从其中发送遥测的服务器或客户端设备。
• InstrumentationKey：Azure 中显示遥测数据的 Application Insights 资源。 它通常从 ApplicationInsights.config 获取。
• 位置：设备的地理位置。
• Operation：在 Web 应用中，为当前的 HTTP 请求。 在其他应用类型中，可以设置此值以将事件组合在一起。
  • ID：一个生成的值，它将不同的事件关联在一起，确保在诊断搜索中检查任何事件时可以发现相关项。
  • 名称：一个标识符，通常是 HTTP 请求的 URL。
  • SyntheticSource：如果不为 null 或空，则此字符串表示请求的源已标识为机器人或 Web 测试。 默认情况下，该属性会从指标资源管理器的计算中排除。
• 会话一致性：用户的会话。 ID 设置为生成的值，当用户有一段时间处于非活动状态时，此值会更改。
• 用户：用户信息。

限制

每个应用程序（即每个检测密钥）的指标和事件数都有一些限制。 限制取决于选择的定价计划。

资源	默认限制	最大限制	备注
每日的总数据量	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	请参阅类型架构。
每个 Application Insights 资源的可用性测试数	100	100
每个资源组的可用性测试计数	800	800	请参阅 Azure 资源管理器
每个测试的可用性测试最大重定向次数	10	10
可用性测试最小测试频率	300 秒		自定义测试频率或频率少于 5 分钟时需要自定义 TrackAvailability 实现。
Profiler 和快照数据保留期	两周	请联系支持人员。 最长保留期限为六个月。
每天发送的探查器数据量	无限制	无限制。
每天发送的快照数据	每个受监视的应用每天 30 个快照	无限制。	可以通过配置修改每个应用程序收集的快照数。

有关定价和配额的详细信息，请参阅 Application Insights 计费。

若要避免达到数据速率限制，请使用采样。

若要确定保留数据的时间期限，请参阅数据保留和隐私。

参考文档

• .NET 参考
• Java 参考
• JavaScript 参考

SDK 代码

• .NET
• Windows Server 包
• Java SDK
• Node.js SDK
• JavaScript SDK

常见问题

本部分提供常见问题的解答。

为什么我缺少遥测数据？

如果在应用程序关闭之前未刷新，则这两个 TelemetryChannel 都将丢失缓冲的遥测数据。

若要避免数据丢失，请在应用程序关闭时刷新 TelemetryClient。

有关详细信息，请参阅刷新数据。

Track_() 调用可能会引发哪些异常？

无。 不需要将它们包装在 try-catch 子句中。 如果 SDK 遇到问题，它会在调试控制台输出中记录消息，如果消息已传入，可在诊断搜索中查看。

是否可以使用某个 REST API 从门户获取数据？

是的，可以使用数据访问 API。 其他用于提取数据的方法包括：Power BI（如果已迁移到基于工作区的资源）或连续导出（如果仍在经典资源上）。

为什么我对自定义事件和指标 API 的调用会被忽略？

Application Insights SDK 与自动检测不兼容。 如果启用了自动检测，将会忽略对 Track() 和其他自定义事件及指标 API 的调用。

在“应用服务”页的“Application Insights”选项卡上禁用 Azure 门户中的自动检测，或将 ApplicationInsightsAgent_EXTENSION_VERSION 设置为 disabled。

为什么搜索图表和指标图表中的计数不一致？

采样减少了从应用发送到门户的遥测项（例如请求和自定义事件）数量。 在搜索中，看到的是接收到的项数。 在显示事件计数的指标图表中，看到的是发生的原始事件数。

传输的每个项都携带一个 itemCount 属性，此属性显示该项表示的原始事件数量。 若要观察操作中的采样，可以在 Log Analytics 中运行此查询：

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

如何设置事件警报？

Azure 警报仅出现在指标上。 创建一个每当事件发生时都跨越值阈值的自定义指标。 然后在该指标上设置警报。 每次指标在任一方向超过阈值时，你都将收到通知。 无论初始值高低，首次超过前都不会收到通知。 通常存在几分钟的延迟。

后续步骤

• 搜索事件和日志