使用 Application Insights 监视 Node.js 应用程序和服务（经典 API）

Application Insights 会在部署后对组件进行监视，以便发现性能问题和其他问题。 可以将 Application Insights 用于 Node.js 服务，不管这些服务是托管在数据中心、Azure VM 和 Web 应用中，还是在其他公有云中。

若要接收、存储和探索监视数据，请将 SDK 包括到代码中。 然后在 Azure 中设置相应的 Application Insights 资源。 SDK 会将数据发送到该资源进行进一步的分析和探索。

Node.js 客户端库可以自动监视传入和传出的 HTTP 请求、异常和某些系统指标。 从 0.20 版开始，客户端库也可监视某些常用的第三方程序包，例如 MongoDB、MySQL、Redis。

所有与传入 HTTP 请求相关的事件都会进行关联，以加快故障排除速度。

可以使用 TelemetryClient API 手动检测和监视应用和系统的其他方面。 本文后面会更详细地介绍 TelemetryClient API。

开始

请完成以下任务，为应用或服务设置监视。

先决条件

开始之前，请确保拥有 Azure 订阅，否则请获取一个新的试用版。 如果组织已经拥有 Azure 订阅，管理员可以按照这些说明将你添加到该订阅。

设置 Application Insights 资源

1. 登录到 Azure 门户。
2. 创建 Application Insights 资源。

设置 Node.js 客户端库

将 SDK 包括到应用中，使之能够收集数据。

1. 从新资源复制资源的连接字符串。 Application Insights 使用连接字符串将数据映射到 Azure 资源。 必须在环境变量或代码中指定连接字符串，然后 SDK 才能使用该连接字符串。

   

2. 通过 package.json 将 Node.js 客户端库添加到应用的依赖项。 从应用的根文件夹，运行：

   npm install applicationinsights --save
   

   注意

   如果使用 TypeScript，请勿安装单独的“typings”包。 此 NPM 包包含内置的 typings。

3. 将该库显式加载到代码中。 由于 SDK 将检测注入到许多其他库中，请尽早加载该库，甚至应赶在其他 require 语句之前加载。

   let appInsights = require('applicationinsights');
   

4. 也可通过环境变量 APPLICATIONINSIGHTS_CONNECTION_STRING 来提供连接字符串，不必手动将其传递给 setup() 或 new appInsights.TelemetryClient()。 这种做法允许将连接字符串脱离已提交的源代码，因此可以为不同的环境指定不同的连接字符串。 若要手动进行配置，请调用 appInsights.setup('[your connection string]');。

   有关其他配置选项，请参阅以下各节。

   可以设置 appInsights.defaultClient.config.disableAppInsights = true，尝试在不发送遥测的情况下使用 SDK。

5. 开始通过调用 appInsights.start(); 自动收集和发送数据。

监视应用

SDK 会自动收集有关 Node.js 运行时和一些常见第三方模块的遥测。 请使用应用程序生成部分此类数据。

然后，在 Azure 门户中转到此前创建的 Application Insights 资源。 在“概览时间线”中，查找前面的几个数据点。 若要查看更多详细数据，请在图表中选择不同的组件。

若要查看应用的已发现拓扑，可以使用应用程序映射。

无数据

由于 SDK 对要提交的数据进行批处理，项目在门户中显示之前可能会有一段延迟。 如果在资源中看不到数据，可尝试下面的部分修复手段：

• 继续使用应用程序。 通过更多操作生成更多遥测。
• 在门户资源视图中选择“刷新”。 图表会定期自行刷新，但手动刷新会强制图表立刻刷新。
• 验证所需传出端口是否已打开。
• 使用搜索查找特定事件。
• 查看常见问题。

基本用法

对于开箱即用的 HTTP 请求集合、受欢迎的第三方库事件、未经处理的异常和系统指标：

let appInsights = require("applicationinsights");
appInsights.setup("[your connection string]").start();

加载其他包之前，请尽早在脚本中加载 Application Insights 库 require("applicationinsights")。 此步骤是必需的，这样 Application Insights 库才能为跟踪准备更高版本的包。 如果与执行类似准备的其他库发生冲突，请尝试稍后加载 Application Insights 库。

由于 JavaScript 处理回调的方式，需要执行额外的工作，以跟踪跨外部依赖项和更高版本回调的请求。 默认情况下，此额外跟踪处于启用状态。 通过调用 setAutoDependencyCorrelation(false) 将其禁用，如 SDK 配置 部分所述。

从版本 0.22 之前的版本进行迁移

这些是版本 0.22 及更高版本之前的版本之间的重大更改。 这些更改旨在与其他 Application Insights SDK 保持一致并允许将来进行扩展。

通常，可以通过以下操作进行迁移：

• 用 appInsights.client 替换对 appInsights.defaultClient 的引用。
• 用 appInsights.getClient() 替换对 new appInsights.TelemetryClient() 的引用。
• 将所有参数替换为 client.track* 方法，其中有一个包含命名属性的对象用作参数。 有关每种类型的遥测的例外对象，请参阅 IDE 的内置类型提示或 TelemetryTypes。

如果在不将 SDK 配置函数链接到 appInsights.setup() 的情况下访问这些函数，现在可以在 appInsights.Configurations 中找到这些函数。 例如 appInsights.Configuration.setAutoCollectDependencies(true)。 查看下一节中对默认配置所做的更改。

SDK 配置

appInsights 对象提供了许多配置方法。 以下代码片段中列出了这些方法及其默认值。

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .setAutoDependencyCorrelation(true)
    .setAutoCollectRequests(true)
    .setAutoCollectPerformance(true, true)
    .setAutoCollectExceptions(true)
    .setAutoCollectDependencies(true)
    .setAutoCollectConsole(true)
    .setUseDiskRetryCaching(true)
    .setSendLiveMetrics(false)
    .setDistributedTracingMode(appInsights.DistributedTracingModes.AI)
    .start();

若要让服务中的事件完全相关联，请确保设置 .setAutoDependencyCorrelation(true)。 设置此选项以后，SDK 即可在 Node.js 中跨异步回调跟踪上下文。

请在 IDE 的内置类型提示或 applicationinsights.ts 中查看其说明，了解详细信息和可选的辅助参数。

分布式跟踪

新式云和 微服务 体系结构实现了简单的独立可部署服务，可降低成本，同时提高可用性和吞吐量。 但是，它使整个系统更难以推理和调试。 分布式跟踪通过提供类似于云和微服务体系结构的调用堆栈的性能探查器来解决此问题。

Azure Monitor 提供了两种使用分布式跟踪数据的体验：单个事务/请求的 事务诊断 视图和 应用程序映射 视图，用于显示系统交互方式。

Application Insights 可以单独监视每个组件，并使用分布式遥测关联来检测哪个组件负责故障或性能下降。 本文介绍 Application Insights 使用的不同语言和平台上的数据模型、上下文传播技术、协议和关联策略的实现。

通过 Application Insights 使用 Autoinstrumentation 或 SDK 启用分布式跟踪。

适用于 .NET、.NET Core、Java、Node.js和 JavaScript 的 Application Insights 代理和 SDK 都支持本机分布式跟踪。

安装并配置正确的 Application Insights SDK 后，SDK 依赖项自动收集器会自动收集常用框架、库和技术的跟踪信息。 依赖项自动收集文档中提供了受支持的技术的完整列表。

可以通过在 TelemetryClient 上调用 TrackDependency 来手动跟踪任意技术。

用于遥测关联的数据模型

Application Insights 为分布式遥测关联定义 数据模型 。 若要将遥测与逻辑操作关联起来，每个遥测项都有一个名为operation_Id的上下文字段。 分布式跟踪中的每个遥测项都共享此标识符。 因此，即使从单个层丢失遥测数据，仍可以关联其他组件报告的遥测数据。

分布式逻辑操作通常由一组较小的操作组成，这些请求由其中一个组件进行处理。 请求遥测 定义这些操作。 每个请求遥测项都有自己的 id，标识它的唯一性和全球性。 与请求关联的所有遥测项（例如跟踪和异常）都应将operation_parentId设置为请求id的值。

依赖项遥测 表示每个传出操作，例如对另一个组件的 HTTP 调用。 它还定义了其自身全局唯一的 id。 请求遥测由这次依赖项调用启动，并使用此 id 作为其 operation_parentId。

可以使用operation_Id、operation_parentId和request.id配合dependency.id来构建分布式逻辑操作的视图。 这些字段还定义了遥测调用的因果关系顺序。

在微服务环境中，来自组件的跟踪可以转到不同的存储项。 每个组件都可以在 Application Insights 中有自己的连接字符串。 若要获取逻辑操作的遥测数据，Application Insights 会查询每个存储项的数据。

当存储项数较大时，需要一个提示，说明下一步要查找的位置。 Application Insights 数据模型定义了两个用于解决此问题的字段： request.source 以及 dependency.target。 第一个字段标识启动依赖项请求的组件。 第二个字段标识哪个组件返回了依赖项调用的响应。

有关从多个不同实例进行查询的信息，请参阅 Azure Monitor 中 Log Analytics 工作区、应用程序和资源的查询数据。

Example

我们来看一个示例。 名为“股票价格”的应用程序使用名为 Stock 的外部 API 显示股票的当前市场价格。 股票价格应用程序中有一个名为“股票”的页面，客户端 Web 浏览器通过 GET /Home/Stock 打开该页面。 应用程序使用 HTTP 调用 GET /api/stock/value查询 Stock API。

可以通过运行查询来分析生成的遥测数据：

(requests | union dependencies | union pageViews)
| where operation_Id == "STYz"
| project timestamp, itemType, name, id, operation_ParentId, operation_Id

在结果中，所有遥测项共享根 operation_Id。 从页面发出 Ajax 调用时，会将新的唯一 ID （qJSXU） 分配给依赖项遥测，并将 pageView 的 ID 用作 operation_ParentId。 然后，服务器请求使用 Ajax ID 作为 operation_ParentId。

对外部服务进行调用 GET /api/stock/value 时，需要知道该服务器的标识，以便可以相应地设置 dependency.target 字段。 当外部服务不支持监视时， target 将设置为服务的主机名。 例如 stock-prices-api.com。 但是，如果服务通过返回预定义的 HTTP 标头来标识自身， target 则包含允许 Application Insights 通过查询该服务的遥测数据来生成分布式跟踪的服务标识。

使用 W3C TraceContext 的关联标头

Application Insights 正在转换为 W3C 跟踪上下文，后者定义：

• traceparent：承载全局唯一的操作 ID 和调用的唯一标识符。
• tracestate：承载特定于系统的跟踪上下文。

Application Insights SDK 的最新版本支持 Trace-Context 协议，但可能需要选择加入该协议。 （保留与 Application Insights SDK 支持的先前相关协议的向后兼容性。

相关 HTTP 协议（也称为 Request-Id）即将弃用。 此协议定义两个标头：

• Request-Id：承载调用的全局唯一 ID。
• Correlation-Context：承载分布式跟踪属性的名称/值对集合。

Application Insights 还定义了相关 HTTP 协议的 扩展 。 它使用 Request-Context 名称-值对来传递直接调用方或被调用方所使用的属性集合。 Application Insights SDK 使用此标头来设置 dependency.target 和 request.source 字段。

W3C Trace-Context和 Application Insights 数据模型的映射方式如下：

有关详细信息，请参阅 Application Insights 遥测数据模型。

采样

默认情况下，SDK 会将收集的所有数据发送到 Application Insights 服务。 如果要启用采样以减少数据量，请在客户端的 samplingPercentage 对象上设置 config 字段。 将 samplingPercentage 设置为 100（默认值）表示将发送所有数据，设置为 0 则表示不会发送任何内容。

如果使用自动关联，则会将与单个请求关联的所有数据作为一个单元包括或排除。

若要启用采样，请添加以下代码：

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.config.samplingPercentage = 33; // 33% of all telemetry will be sent to Application Insights
appInsights.start();

多组件应用程序的多个角色

在某些情况下，应用程序可能包含多个组件，你希望使用相同的连接字符串对所有这些组件进行检测。 你希望仍将这些组件视为门户中的单独单元，就像它们使用的是单独的连接字符串一样。 例如，应用程序映射上的单独节点。 需要手动配置 RoleName 字段，以便将一个组件的遥测与发送到 Application Insights 资源的其他组件区分开来。

使用以下代码设置 RoleName 字段：

const appInsights = require("applicationinsights");
appInsights.setup("<connection_string>");
appInsights.defaultClient.context.tags[appInsights.defaultClient.context.keys.cloudRole] = "MyRoleName";
appInsights.start();

浏览器 SDK 加载程序

可以在配置中通过 JavaScript (Web) SDK 加载程序脚本注入为节点服务器启用自动 Web 检测。

let appInsights = require("applicationinsights");
appInsights.setup("<connection_string>")
    .enableWebInstrumentation(true)
    .start();

或设置环境变量 APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_ENABLED = true 为节点服务器启用自动 Web 检测。

满足以下所有要求时，将对节点服务器响应启用 Web 检测：

• 响应的状态代码为 200。
• 响应方法为 GET。
• 服务器响应具有 Content-Type html。
• 服务器响应同时包含 <head> 和 </head> 标记。
• 如果响应已压缩，则它必须只有一种 Content-Encoding 类型，并且编码类型必须是 gzip、br 或 deflate 中的一种。
• 响应不包含当前的 /backup Web 检测 CDN 终结点。 （此处为当前和备份 Web 检测 CDN 终结点）

可以通过设置环境变量 APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_SOURCE = "web Instrumentation CDN endpoints" 来更改 Web 仪表 CDN 终结点。 可以通过设置环境变量来更改 Web 仪表连接字符串 APPLICATIONINSIGHTS_WEB_INSTRUMENTATION_CONNECTION_STRING = "web Instrumentation connection string"

自动第三方检测

为了跨异步调用跟踪上下文，某些第三方库（如 MongoDB 和 Redis）需要进行一些更改。 默认情况下，Application Insights 将使用 diagnostic-channel-publishers 以对其中部分库进行猴式修补。 可通过设置 APPLICATION_INSIGHTS_NO_DIAGNOSTIC_CHANNEL 环境变量禁用此功能。

可以通过将 APPLICATION_INSIGHTS_NO_PATCH_MODULES 环境变量设置为要禁用的包的逗号分隔列表来禁用单个猴子补丁。 例如，使用 APPLICATION_INSIGHTS_NO_PATCH_MODULES=console,redis 以避免修补 console 和 redis 包。

目前已检测到 9 个包：bunyan、console、mongodb、mongodb-core、mysql、redis、winston、pg 和 pg-pool。 有关修补这些包的哪个确切版本的信息，请访问 diagnostic-channel-publishers 自述文件。

bunyan、winston 和 console 补丁会根据是否启用 setAutoCollectConsole 生成 Application Insights 跟踪事件。 其余补丁会根据是否启用 setAutoCollectDependencies 生成 Application Insights 依赖项事件。

实时指标

若要允许将实时指标从应用发送到 Azure，请使用 setSendLiveMetrics(true)。 目前，不支持在门户中筛选实时指标。

扩展指标

若要允许将扩展本机指标从应用发送到 Azure，请安装单独的本机指标包。 SDK 会在安装后自动加载，并开始收集 Node.js 原生指标。

npm install applicationinsights-native-metrics

目前，本机指标包会自动收集垃圾回收 CPU 时间、事件循环计时和堆使用情况：

• 垃圾回收：每种类型的垃圾回收所用的 CPU 时间，以及每种类型出现的次数。
• 事件循环：发生了多少个计时周期，以及总共花费了多少 CPU 时间。
• 堆与非堆：应用的内存使用量有多少位于堆或非堆中。

分布式跟踪模式

默认情况下，SDK 会发送被其他应用程序或服务理解的标头，可通过 Application Insights SDK 检测到此类应用程序或服务。 除了现有的 AI 标头，还可以启用 W3C 跟踪上下文标头的发送和接收。 这样就不会中断与任何现有旧服务的关联。 通过启用 W3C 标头，可将应用与未通过 Application Insights 检测的其他服务关联，但会采用这一 W3C 标准。

const appInsights = require("applicationinsights");
appInsights
  .setup("<your connection string>")
  .setDistributedTracingMode(appInsights.DistributedTracingModes.AI_AND_W3C)
  .start()

TelemetryClient API

有关 TelemetryClient API 的完整说明，请参阅用于处理自定义事件和指标的 Application Insights API。

可以使用 Node.js 的 Application Insights 客户端库跟踪任何请求、事件、指标或异常。 以下代码示例演示了部分可用 API：

let appInsights = require("applicationinsights");
appInsights.setup().start(); // assuming connection string in env var. start() can be omitted to disable any non-custom data
let client = appInsights.defaultClient;
client.trackEvent({name: "my custom event", properties: {customProperty: "custom property value"}});
client.trackException({exception: new Error("handled exceptions can be logged with this method")});
client.trackMetric({name: "custom metric", value: 3});
client.trackTrace({message: "trace message"});
client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:231, resultCode:0, success: true, dependencyTypeName: "ZSQL"});
client.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

let http = require("http");
http.createServer( (req, res) => {
  client.trackNodeHttpRequest({request: req, response: res}); // Place at the beginning of your request handler
});

跟踪依赖项

使用以下代码跟踪依赖项：

let appInsights = require("applicationinsights");
let client = new appInsights.TelemetryClient();

var success = false;
let startTime = Date.now();
// execute dependency call here....
let duration = Date.now() - startTime;
success = true;

client.trackDependency({target:"http://dbname", name:"select customers proc", data:"SELECT * FROM Customers", duration:duration, resultCode:0, success: true, dependencyTypeName: "ZSQL"});;

使用 trackMetric 度量事件循环计划所花费的时间的示例实用工具：

function startMeasuringEventLoop() {
  var startTime = process.hrtime();
  var sampleSum = 0;
  var sampleCount = 0;

  // Measure event loop scheduling delay
  setInterval(() => {
    var elapsed = process.hrtime(startTime);
    startTime = process.hrtime();
    sampleSum += elapsed[0] * 1e9 + elapsed[1];
    sampleCount++;
  }, 0);

  // Report custom metric every second
  setInterval(() => {
    var samples = sampleSum;
    var count = sampleCount;
    sampleSum = 0;
    sampleCount = 0;

    if (count > 0) {
      var avgNs = samples / count;
      var avgMs = Math.round(avgNs / 1e6);
      client.trackMetric({name: "Event Loop Delay", value: avgMs});
    }
  }, 1000);
}

将自定义属性添加到所有事件

使用以下代码向所有事件添加自定义属性：

appInsights.defaultClient.commonProperties = {
  environment: process.env.SOME_ENV_VARIABLE
};

跟踪 HTTP GET 请求

使用以下代码手动跟踪 HTTP GET 请求：

appInsights.defaultClient.trackRequest({name:"GET /customers", url:"http://myserver/customers", duration:309, resultCode:200, success:true});

也可使用 trackNodeHttpRequest 方法跟踪请求：

var server = http.createServer((req, res) => {
  if ( req.method === "GET" ) {
      appInsights.defaultClient.trackNodeHttpRequest({request:req, response:res});
  }
  // other work here....
  res.end();
});

跟踪服务器启动时间

使用以下代码跟踪服务器启动时间：

let start = Date.now();
server.on("listening", () => {
  let duration = Date.now() - start;
  appInsights.defaultClient.trackMetric({name: "server startup time", value: duration});
});

刷新

默认情况下，遥测数据在发送到引入服务器之前会缓冲 15 秒。 如果应用程序的生存期较短（例如 CLI 工具就是如此），则可能需要在应用程序终止时使用 appInsights.defaultClient.flush() 手动刷新缓冲的遥测。

如果 SDK 检测到应用程序正在崩溃，它会使用 appInsights.defaultClient.flush({ isAppCrashing: true }) 为你调用刷新。 如果使用刷新选项 isAppCrashing，应用程序会被认为处于异常状态，不适合发送遥测。 改为由 SDK 把所有缓冲的遥测数据保存到持久存储，并让应用程序终止。 当应用程序重新启动时，它会尝试发送已保存到持久存储中的遥测数据。

筛选和预处理遥测

在从 SDK 发送遥测数据之前，可以编写代码来筛选、修改或扩充遥测数据。 处理包括从标准遥测模块发送的数据，例如 HTTP 请求集合和依赖项收集。

• 筛选 可以在通过 SDK 发送遥测数据之前，修改或丢弃这些数据，通过实现 ITelemetryProcessor。 例如，可以通过排除来自机器人的请求来减少遥测数据量。 与采样不同，你可以完全控制发送或丢弃的内容，但它会影响基于聚合日志的任何指标。 根据您丢弃项的方式，可能还会失去在相关项之间导航的可能性。

• 通过实现ITelemetryInitializer，为应用发送的任何遥测数据添加或修改属性。 例如，可以添加计算值或版本号，以便筛选门户中的数据。

• 采样 可减少遥测量，而不会影响统计信息。 它会将相关的数据点放在一起，以便在诊断问题时在它们之间导航。 在门户中，总计数被乘以一个系数，以补偿采样的影响。

Filtering

通过此方法，你可以直接控制遥测流中包括或排除的内容。 筛选可用于删除发送到 Application Insights 的遥测项。 可以将筛选与采样结合使用，也可以单独使用。

若要筛选遥测数据，请编写遥测处理器并将其注册到 TelemetryConfiguration。 所有遥测都经过你的处理器。 可以选择将其从流中删除，或将其提供给链中的下一个处理器。 包括来自标准模块的遥测数据，例如 HTTP 请求收集器和依赖项收集器，以及你自己跟踪的遥测数据。 例如，可以筛选出机器人发出的请求或成功的依赖调用的遥测数据。

ITelemetryProcessor 和 ITelemetryInitializer

遥测处理器和遥测初始值设定项有何区别？

• 在使用它们时可以做的事情有一些重叠。 这两者都可用于添加或修改遥测的属性，不过我们建议出于此目的使用初始值设定项。
• 遥测初始值设定项始终在遥测处理器之前运行。
• 遥测初始值设定项可以多次调用。 按照约定，它们不会设置任何已设置的属性。
• 遥测处理器允许完全替换或放弃遥测项。
• 所有注册的遥测初始化程序都会被调用，以处理每个遥测项。 对于遥测处理器，SDK 保证调用第一个遥测处理器。 其余处理器是否被调用取决于前面的遥测处理器。
• 使用遥测初始化程序用更多属性丰富遥测数据，或覆盖现有属性。 使用遥测处理器筛选出遥测数据。

添加/修改属性

使用遥测初始化程序使用额外信息丰富遥测数据，或替代标准遥测模块设置的遥测属性。

例如，Web 包的 Application Insights 收集有关 HTTP 请求的遥测数据。 默认情况下，它会将响应代码 >=400 的任何请求标记为失败。 如果要将 400 视为成功，可以定义一个设置 success 属性的遥测初始值设定项。

如果提供了遥测初始化器，则在调用任何 Track*() 方法时都会调用它。 此初始化程序包括调用标准遥测模块的方法Track()。 按照约定，这些模块不会设置已由初始值设定项设置的任何属性。 在调用遥测处理器之前调用遥测初始值设定项，因此初始值设定项执行的任何扩充对处理器都可见。

使用遥测处理器预处理数据

在发送收集的数据进行保留之前，可以使用遥测处理器来处理和筛选这些数据。 遥测处理器在遥测项发送到云之前按其添加顺序依次调用。

public addTelemetryProcessor(telemetryProcessor: (envelope: Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

如果遥测处理器返回 false，则不会发送该遥测项。

所有遥测处理器都接收遥测数据及其信封来检查和修改。 它们还会接收上下文对象。 在为手动跟踪的遥测调用跟踪方法时，此对象的内容由 contextObjects 参数定义。 对于自动收集的遥测，此对象使用 appInsights.getCorrelationContext() 提供的可用请求信息和持久性请求内容（如果启用了自动相关性关联）进行填充。

遥测处理器的 TypeScript 类型为：

telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean;

例如，可以按如下所示编写并添加从异常中删除堆栈跟踪数据的处理器：

function removeStackTraces ( envelope, context ) {
  if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
    var data = envelope.data.baseData;
    if (data.exceptions && data.exceptions.length > 0) {
      for (var i = 0; i < data.exceptions.length; i++) {
        var exception = data.exceptions[i];
        exception.parsedStack = null;
        exception.hasFullStack = false;
      }
    }
  }
  return true;
}

appInsights.defaultClient.addTelemetryProcessor(removeStackTraces);

添加云角色名称和云角色实例

通过直接上下文标记设置云角色名称：

var appInsights = require("applicationinsights");
appInsights.setup('INSTRUMENTATION_KEY').start();
appInsights.defaultClient.context.tags["ai.cloud.role"] = "your role name";
appInsights.defaultClient.context.tags["ai.cloud.roleInstance"] = "your role instance";

通过遥测处理器设置云角色名称：

var appInsights = require("applicationinsights");
appInsights.setup('INSTRUMENTATION_KEY').start();

appInsights.defaultClient.addTelemetryProcessor(envelope => {
    envelope.tags["ai.cloud.role"] = "your role name";
    envelope.tags["ai.cloud.roleInstance"] = "your role instance"
});

使用多个连接字符串

可以创建多个 Application Insights 资源，并使用各自的连接字符串将不同数据发送到每个资源。

例如：

let appInsights = require("applicationinsights");

// configure auto-collection under one connection string
appInsights.setup("Connection String A").start();

// track some events manually under another connection string
let otherClient = new appInsights.TelemetryClient("Connection String B");
otherClient.trackEvent({name: "my custom event"});

高级配置选项

客户端对象包含一个 config 属性，该属性具有多个适用于高级方案的可选设置。 若要设置它们，请使用：

client.config.PROPERTYNAME = VALUE;

这些属性是特定于客户端的，因此你可以从使用 appInsights.defaultClient 创建的客户端单独配置 new appInsights.TelemetryClient()。

自定义事件和指标的核心 API

在应用程序中插入几行代码，以了解用户如何使用它，或帮助诊断问题。 可以从设备和桌面应用、Web 客户端和 Web 服务器发送遥测数据。 使用 Application Insights 核心遥测 API 发送自定义事件和指标以及自己的标准遥测版本。 此 API 与标准 Application Insights 数据收集器使用的 API 相同。

API 摘要

除了一些变体 GetMetric （仅限 .NET）外，核心 API 在所有平台上都是统一的。

可以将属性和指标附加到其中的大多数遥测调用。

先决条件

如果您尚未引用 Application Insights SDK，请注意以下步骤：

1. 将 Application Insights SDK 添加到项目。

2. 在设备或 Web 服务器代码中，包括：

   • .NET
   • Node.js

   using Microsoft.ApplicationInsights;
   

获取 TelemetryClient 实例

获取TelemetryClient的实例

private TelemetryClient telemetry = new TelemetryClient();

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

var telemetry = applicationInsights.defaultClient;

TrackEvent

在 Application Insights 中， 自定义事件 是一个数据点，可以在 指标资源管理器 中显示为聚合计数，并在 诊断搜索 中显示为单个事件。 （它与 MVC 或其他框架“events”无关）。

在代码中插入 TrackEvent 调用以计算各种事件。 例如，你可能希望跟踪用户选择特定功能的频率。 或者，你可能想知道他们达到特定目标的频率或犯特定类型的错误。

例如，在游戏应用中，每当用户赢得游戏时发送事件：

telemetry.TrackEvent("WinGame");

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

Log Analytics 中的自定义事件

customEvents选项卡或使用体验的表中提供了遥测数据。 事件可能来自trackEvent(..)或点击分析自动收集插件。

如果 采样 正在运行，该 itemCount 属性将显示大于 1的值。 例如，itemCount==10 指在 10 次 trackEvent() 调用中，采样过程只传输了其中一个。 若要获取自定义事件的正确计数，请使用代码，例如 customEvents | summarize sum(itemCount)。

GetMetric

若要了解如何有效地使用 GetMetric() 调用捕获 .NET 和 .NET Core 应用程序的本地预聚合指标，请参阅 .NET 和 .NET Core 中的自定义指标集合。

TrackMetric

Application Insights 可以为没有附加到特定事件的指标绘制图表。 例如，可以定期监视队列长度。 使用指标时，各个度量值的关注低于变化和趋势，因此统计图表非常有用。

若要将指标发送到 Application Insights，可以使用 TrackMetric(..) API。 可通过两种方式发送指标：

• 单个值。 每次在应用程序中执行度量时，都会将相应的值发送到 Application Insights。

  例如，假设你有一个指标来描述容器中的项数。 在特定时间段内，首先将三个项放入容器中，然后删除两个项。 因此，你会调用 TrackMetric 两次。 首先，传递该值 3 ，然后传递值 -2。 Application Insights 为你存储这两个值。

• 聚合。 使用指标时，单个测量值通常不引人关注。 相反，对特定时间段内所发生的事情的摘要非常重要。 此类摘要称为 聚合。

  在前面的示例中，该时间段的聚合度量总和为1，而指标值的计数为2。 使用聚合方法时，每个时间段只调用 TrackMetric 一次并发送聚合值。 建议使用此方法，因为它可以通过向 Application Insights 发送更少的数据点来显著降低成本和性能开销，同时仍收集所有相关信息。

单个值示例

发送单个指标值：

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

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

Log Analytics 中的自定义指标

customMetrics 的 表中提供了遥测数据。 每一行表示应用中的 trackMetric(..) 调用。

• valueSum：度量之和。 若要获取平均值，请除以 valueCount。
• valueCount：聚合到此 trackMetric(..) 调用中的测量次数。

页面视图

在设备或网页应用中，加载每个屏幕或页面时，默认情况下会发送页面视图遥测数据。 但是，可以更改默认值，以在更多时间点或不同时间段跟踪页面视图。 例如，在显示选项卡或窗格的应用中，你可能希望在用户打开新窗格时跟踪页面。

用户和会话数据作为属性与页面视图一起发送，因此当存在页面视图遥测时，用户和会话图表会变得活跃。

自定义页面视图

telemetry.TrackPageView("GameReviewPage");

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 轻松查找与请求关联的任何事件。

手动跟踪遥测时，确保遥测关联的最简单方法是使用此模式：

// Establish an operation context and associated telemetry item:
using (var operation = telemetryClient.StartOperation<RequestTelemetry>("operationName"))
{
    // Telemetry sent in here uses 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.

// Establish an operation context and associated telemetry item:
const operation = appInsights.startOperation(client, { name: "operationName" });

appInsights.wrapWithCorrelationContext(() => {
    // Telemetry sent in here uses the same operation ID.
    ...
    client.trackTrace({ message: "..." }); // or other track* calls
    ...

    // Set properties of containing telemetry item—for example:
    operation.telemetry.responseCode = "200";

    // Optional: explicitly send telemetry item:
    client.stopOperation(operation);

}, operation.context)(); // When callback completes, telemetry item is sent.

除了设置作上下文， StartOperation 还创建指定的类型的遥测项。 在处理操作时，或如果显式调用 StopOperation，它将发送遥测项。 如果使用 RequestTelemetry 遥测类型，则其持续时间设置为开始和停止之间的时间间隔。

在某个操作范围内报告的遥测项将成为该操作的子项。 操作上下文可以嵌套。

在 搜索中，作上下文用于创建 相关项 列表。

有关自定义操作跟踪的更多信息，请参阅 使用 Application Insights .NET SDK 跟踪自定义操作。

Log Analytics 中的请求

在 Application Insights Analytics 中，请求显示在 requests 表中。

如果 采样 正在运行，该 itemCount 属性将显示大于 1的值。 例如，itemCount==10 指在 10 次 trackRequest() 调用中，采样过程只传输了其中一个。 若要获取按请求名称分段的请求数和平均持续时间的正确计数，请使用如下代码：

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

TrackException

将异常发送到 Application Insights：

• 若要 对它们进行计数，用来指示问题出现的频率。
• 检查单个事件。

报告包括堆栈跟踪。

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

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

SDK 自动捕获许多异常，因此并不总是必须显式调用 TrackException 。

Log Analytics 中的异常

在 Application Insights Analytics 中，表中会显示 exceptions 异常。

如果 采样 正在运行，该 itemCount 属性将显示大于 1的值。 例如，itemCount==10 指在 10 次 trackException() 调用中，采样过程只传输了其中一个。 若要获取按异常类型分段的正确异常计数，请使用如下代码：

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 来帮助诊断问题。 可以发送诊断数据的区块，并在 诊断搜索中检查它们。

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

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

记录诊断事件，比如进入或退出函数。

可以搜索消息内容，但与属性值不同，无法对其进行筛选。

message 的大小限制远高于属性的限制。 一个优点是 TrackTrace 能将相对较长的数据放入消息中。 例如，可以在那里对 POST 数据进行编码。

还可以向邮件添加严重性级别。 与其他遥测一样，可以添加属性值来帮助筛选或搜索不同的跟踪集。 例如：

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

在 “搜索”中，可以轻松筛选出与特定数据库相关的特定严重性级别的所有消息。

Log Analytics 中的跟踪记录

在 Application Insights Analytics 中，对 TrackTrace 的调用会显示在 traces 表中。

如果 采样 正在运行，该 itemCount 属性将显示大于 1的值。 例如，itemCount==10 指在 10 次 trackTrace() 调用中，采样过程只传输了其中一个。 若要获取正确的跟踪调用计数，请使用代码，例如 traces | summarize sum(itemCount)。

TrackDependency

使用 TrackDependency 调用来跟踪对外部代码段的响应时间和调用成功率。 结果显示在门户中的依赖项图表中。 在进行依赖项调用时，必须添加以下代码片段。

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

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。 必须在服务器上安装代理才能使模块正常工作。

如果您想跟踪自动跟踪系统未检测到的调用，请使用此调用。

若要在 C# 中关闭标准依赖项跟踪模块，请编辑 ApplicationInsights.config 并删除对 DependencyCollector.DependencyTrackingTelemetryModule的引用。

Log Analytics 中的依赖项

在 Application Insights Analytics 中， trackDependency 调用显示在 dependencies 表中。

如果 采样 正在运行，则 itemCount 属性显示大于 1 的值。 例如，itemCount==10 指在 10 次 trackDependency() 调用中，采样过程只传输了其中一个。 若要获取按目标组件分段的正确依赖项计数，请使用如下代码：

dependencies
| summarize sum(itemCount) by target

若要将依赖项与其相关请求相关联，请使用联接：

dependencies
| join (requests) on operation_Id

清除数据

通常，SDK 会以固定间隔（通常是 30 秒）或缓冲区满时（通常是 500 个项目）发送数据。 在某些情况下，可能需要刷新缓冲区。 在一个即将关闭的应用程序中使用 SDK 的一个示例是。

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

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

telemetry.flush();

经过身份验证的用户

在 Web 应用中，默认情况下，用户 由 Cookie 标识 。 如果用户从其他计算机或浏览器访问你的应用，或者如果用户删除 Cookie，则可能会多次计数。

如果用户登录到应用，可以通过在浏览器代码中设置经过身份验证的用户 ID 来获取更准确的计数。 无需使用用户的实际登录名称。 它只能是该用户唯一的 ID。 它不得包含空格或任何字符 ,;=|。

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

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

在 指标资源管理器中，可以创建统计 用户、已验证和 用户帐户的图表。

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

使用属性筛选、搜索并分类您的数据

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

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

字符串长度限制为 8,192。 如果要发送大块数据，请使用消息参数 TrackTrace。

指标 是可以以图形方式呈现的数值。 例如，你可能想要查看玩家的分数是否逐渐增加。 图形可以按随事件一起发送的属性进行分段，以便可以获取不同游戏的单独或堆积图。

指标值应大于或等于 0 才能正确显示。

可以使用的 属性、属性值和指标数量 有一些限制。

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

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

设置属性和指标的替代方法

如果更方便，可以在单独的对象中收集事件的参数：

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

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()。

计时事件

有时你可能需要记录完成动作所需的时间。 例如，你可能想要了解用户在游戏中考虑选择的时间。 若要获取此信息，请使用度量参数。

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

自定义遥测的默认属性

如果要为编写的某些自定义事件设置默认属性值，请在实例中 TelemetryClient 设置它们。 它们附加在从客户端发送的每一项遥测数据上。

using Microsoft.ApplicationInsights.DataContracts;

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

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

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

单个遥测调用可以替代其属性字典中的默认值。

若要为所有遥测数据（包括标准收集模块的数据）添加属性，请实现 。

禁用遥测

若要 动态停止和启动 遥测的收集和传输，请执行以下步骤：

using  Microsoft.ApplicationInsights.Extensibility;

TelemetryConfiguration.Active.DisableTelemetry = true;

telemetry.config.disableAppInsights = true;

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

开发人员模式

在调试期间，使遥测数据在管道中快速传输非常有用，以便能立即查看结果。 还可以获取其他消息，这些消息可帮助你跟踪遥测问题。 在生产中将其关闭，因为它可能会减慢你的应用速度。

TelemetryConfiguration.Active.TelemetryChannel.DeveloperMode = true;

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

设置所选自定义遥测的仪表密钥

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

动态连接字符串

为了避免混合开发、测试和生产环境中的遥测数据，可以 创建单独的 Application Insights 资源 并更改其密钥，具体取决于环境。

可以在代码中设置检测密钥，而不是从配置文件中获取检测密钥。 在初始化方法中设置密钥，例如 global.aspx.cs 在 ASP.NET 服务中：

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

TelemetryContext

TelemetryClient 具有 Context 属性，其中包含随所有遥测数据一起发送的值。 它们通常由标准遥测模块设置，但你也可以自行设置它们。 例如：

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

如果你自行设置这些值中的任何一个，请考虑从 ApplicationInsights.config 中删除相关行，以便你的值和标准值不会感到困惑。

• 组件：应用及其版本。
• 设备：有关运行应用的设备的数据。 在 Web 应用中，遥测是从服务器或客户端设备传输的。
• InstrumentationKey：Azure 中用于显示遥测数据的 Application Insights 资源。 它通常从 ApplicationInsights.config加载。
• 位置：设备的地理位置。
• 操作：在 Web 应用中，当前 HTTP 请求。 在其他应用类型中，可以将此值设置为将事件组合在一起。
  • ID：生成的值，该值关联不同的事件，以便在诊断搜索中检查任何事件时，可以找到相关项。
  • 名称：标识符，通常是 HTTP 请求的 URL。
  • SyntheticSource：如果不是 null 或为空，则表示请求的源已标识为机器人或 Web 测试。 在默认情况下，它不会被包括在度量探索器中的计算中。
• 会话：用户的会话。 ID 设置为生成的值，当用户一段时间未处于活动状态时会更改该值。
• 用户：用户信息。

限制

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

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

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

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

故障排除

有关故障排除信息（包括“无数据”方案和自定义日志），请参阅对 Node.js 应用和服务的 Application Insights 监视进行故障排除。

后续步骤

• 若要查看常见问题解答（FAQ），请参阅：
  • Node.js 常见问题解答
  • 用于自定义事件和指标的 Application Insights API 常见问题解答
• 在门户中监视遥测数据。
• 了解如何使用 Log Analytics 并通过 遥测编写分析查询。