用于 TypeScript 的 Application Insights JavaScript SDK（Web）

当您需要使用 Application Insights JavaScript SDK（@microsoft/applicationinsights-web）监控仪器浏览器/网页应用时，请使用此技能。用于真实用户监控（RUM）——页面浏览、点击、AJAX/fetch 依赖、异常、自定义事件，以及与后端相关的浏览器端生成式 AI 代理追踪...

使用 @microsoft/applicationinsights-web 对浏览器应用进行真实用户监控（RUM）。自动收集页面浏览、AJAX/fetch 依赖、未处理异常，以及（通过 Click Analytics 插件）点击事件。支持自定义事件、指标以及遵循 OpenTelemetry GenAI 语义规范的 GenAI 代理跟踪，并通过 W3C Trace Context 与后端跨度关联。

搜索 microsoft-docs MCP 以获取当前的 API 模式：

@microsoft/applicationinsights-web Core RUM SDK (page views, AJAX, exceptions).

@microsoft/applicationinsights-clickanalytics-js Auto-collect click telemetry.

@microsoft/applicationinsights-react-js React plugin (router instrumentation, hooks, HOC, ErrorBoundary).

@microsoft/applicationinsights-react-native React Native plugin (native crashes, sessions).

@microsoft/applicationinsights-angularplugin-js Angular plugin (router events, ErrorHandler).

@microsoft/applicationinsights-debugplugin-js Dev-only telemetry inspector.

@microsoft/applicationinsights-perfmarkmeasure-js User Timing (performance.mark/measure) integration.

npm i --save @microsoft/applicationinsights-web
# Optional plugins (install only what you use):
npm i --save @microsoft/applicationinsights-clickanalytics-js
npm i --save @microsoft/applicationinsights-react-js @microsoft/applicationinsights-react-native @microsoft/applicationinsights-angularplugin-js

类型定义随包一起提供——无需单独安装 @types/...。

浏览器 SDK 在初始化时需要连接字符串。它以明文形式传输给客户端——浏览器遥测不支持 Microsoft Entra ID 身份验证。如果需要将浏览器 RUM 与后端遥测隔离，请使用启用本地身份验证的独立 App Insights 资源。

# Vite / CRA / Next.js — expose to client via the public env prefix
VITE_APPINSIGHTS_CONNECTION_STRING="InstrumentationKey=...;IngestionEndpoint=https://...;LiveEndpoint=https://..."
NEXT_PUBLIC_APPINSIGHTS_CONNECTION_STRING="InstrumentationKey=..."

import { ApplicationInsights } from "@microsoft/applicationinsights-web";

export const appInsights = new ApplicationInsights({
  config: {
    connectionString: import.meta.env.VITE_APPINSIGHTS_CONNECTION_STRING,
    enableAutoRouteTracking: true,        // SPA route changes -> page views
    enableCorsCorrelation: true,          // propagate Request-Id / traceparent to cross-origin AJAX
    enableRequestHeaderTracking: true,
    enableResponseHeaderTracking: true,
    distributedTracingMode: 2,            // DistributedTracingModes.AI_AND_W3C — emit traceparent for backend correlation
    autoTrackPageVisitTime: true,
    disableFetchTracking: false,          // fetch() is auto-instrumented by default
    excludeRequestFromAutoTrackingPatterns: [/livemetrics\.azure\.com/i]
  }
});

appInsights.loadAppInsights();
appInsights.trackPageView();

尽早且只调用一次 loadAppInsights()（在要跟踪的用户交互之前）。然后为初始加载调用 trackPageView() —— 当启用 enableAutoRouteTracking 时，后续的路由变化会自动跟踪。

当你希望使用自动更新的 SDK 并且无需构建流程时，推荐使用。在 中将其作为 第一个 粘贴：

仅限加载器的 API（在 SDK 加载前排队）：trackEvent、trackPageView、trackException、trackTrace、trackDependencyData、trackMetric、trackPageViewPerformance、startTrackPage、stopTrackPage、startTrackEvent、stopTrackEvent、addTelemetryInitializer、setAuthenticatedUserContext、clearAuthenticatedUserContext、flush。

// Page views (SPAs that disable enableAutoRouteTracking)
appInsights.trackPageView({ name: "Checkout", uri: "/checkout", properties: { cartSize: 3 } });

// Custom events (user actions, business events)
appInsights.trackEvent({ name: "PurchaseCompleted" }, { orderId: "ord_123", amountUsd: 49.95 });

// Exceptions (caught errors)
try {
  await pay(order);
} catch (err) {
  appInsights.trackException({ exception: err as Error, severityLevel: 3, properties: { orderId: order.id } });
}

// Traces (logs, severity 0=Verbose, 1=Info, 2=Warning, 3=Error, 4=Critical)
appInsights.trackTrace({ message: "Cart hydrated from local storage", severityLevel: 1 });

// Custom metrics (numeric)
appInsights.trackMetric({ name: "checkout.duration_ms", average: 1234 });

// Dependencies (manually-tracked outbound calls — fetch/XHR are auto-tracked)
appInsights.trackDependencyData({
  id: crypto.randomUUID(),
  name: "GET /api/orders",
  duration: 87, success: true, responseCode: 200,
  data: "https://api.example.com/api/orders", target: "api.example.com", type: "Fetch"
});

// User identity (set ONCE per authenticated session — values are PII; do not pass emails)
appInsights.setAuthenticatedUserContext("user-id-123", "tenant-456", /*storeInCookie*/ true);
appInsights.clearAuthenticatedUserContext(); // on logout

// Force send before unload
appInsights.flush();

在发送之前对每个信封运行。返回 false 以丢弃。

import type { ITelemetryItem } from "@microsoft/applicationinsights-web";

appInsights.addTelemetryInitializer((item: ITelemetryItem) => {
  item.tags ??= {};
  item.tags["ai.cloud.role"] = "web-shop";
  item.tags["ai.cloud.roleInstance"] = window.location.hostname;
  item.data ??= {};
  item.data["app.version"] = import.meta.env.VITE_APP_VERSION;
  item.data["app.build"] = import.meta.env.VITE_BUILD_SHA;

  // Drop noisy health-check page views
  if (item.baseType === "PageviewData" && item.baseData?.uri?.endsWith("/healthz")) return false;

  // Scrub query-string secrets
  if (item.baseData?.uri) {
    item.baseData.uri = item.baseData.uri.replace(/([?&](https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-typescript/skills/applicationinsights-web-ts/token|sig|key)=)[^&]+/gi, "$1REDACTED");
  }
});

import { ClickAnalyticsPlugin } from "@microsoft/applicationinsights-clickanalytics-js";

const clickPlugin = new ClickAnalyticsPlugin();
const appInsights = new ApplicationInsights({
  config: {
    connectionString: import.meta.env.VITE_APPINSIGHTS_CONNECTION_STRING,
    extensions: [clickPlugin],
    extensionConfig: {
      [clickPlugin.identifier]: {
        autoCapture: true,
        dataTags: { useDefaultContentNameOrId: true, customDataPrefix: "data-ai-" },
        urlCollectHash: false,
        behaviorValidator: (b: string) => /^[a-z0-9_]+$/.test(b) ? b : ""
      }
    }
  }
});
appInsights.loadAppInsights();

使用 data-ai-* 属性标记元素；点击会作为带有父级内容元数据的自定义事件发出。

设置 distributedTracingMode: 2（DistributedTracingModes.AI_AND_W3C）。SDK 会在外发的 fetch/XHR 中添加 traceparent（以及遗留的 Request-Id）。使用 OpenTelemetry（例如 @azure/monitor-opentelemetry）进行的后端监测会自动与浏览器的 operation_Id 关联。

对于跨源调用，也要设置 enableCorsCorrelation: true 并将调用来源添加到 API 的 CORS 暴露头 中。

GenAI 代理跟踪（OTel 语义约定）

当浏览器调用 AI 代理（函数调用、工具使用、直接从客户端调用模型）时，发送 App Insights Dependency 遥测，其属性遵循 OpenTelemetry GenAI 语义规范，以便可以在 App Insights / Log Analytics 中与后端代理跨度一起查询。

首先设置选择加入的环境，以便后端工具使用相同的模式版本：

OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental

必需的属性键（按原样使用 OTel 名称）

invoke_agent {agent.name} gen_ai.operation.name=invoke_agent, gen_ai.provider.name, gen_ai.agent.name, gen_ai.agent.id (when known)

create_agent {agent.name} gen_ai.operation.name=create_agent, gen_ai.provider.name, gen_ai.agent.name, gen_ai.request.model

chat {model} gen_ai.operation.name=chat, gen_ai.provider.name, gen_ai.request.model, gen_ai.response.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens

execute_tool {tool.name} gen_ai.operation.name=execute_tool, gen_ai.tool.name, gen_ai.tool.type (function \ extension \ datastore), gen_ai.tool.call.id

gen_ai.provider.name 常用值：openai、azure.ai.openai、azure.ai.inference、anthropic、aws.bedrock、gcp.gemini、gcp.vertex_ai、cohere、mistral_ai、groq、deepseek、perplexity、x_ai、ibm.watsonx.ai。

模式：调用代理 嵌套工具/模型跨度

import { ApplicationInsights, SeverityLevel } from "@microsoft/applicationinsights-web";

type GenAiAttrs = Record<string, string | number | boolean | undefined>;

function startGenAiSpan(name: string, attrs: GenAiAttrs) {
  const id = crypto.randomUUID();
  const start = performance.now();
  const baseProps: GenAiAttrs = { "gen_ai.span.id": id, ...attrs };
  return {
    end(success: boolean, extra: GenAiAttrs = {}, error?: Error) {
      const duration = Math.round(performance.now() - start);
      const properties = { ...baseProps, ...extra };
      appInsights.trackDependencyData({
        id, name, duration, success,
        responseCode: error ? 500 : 200,
        type: "GenAI",
        target: String(attrs["gen_ai.provider.name"] ?? "genai"),
        properties: properties as Record<string, string>
      });
      if (error) {
        appInsights.trackException({
          exception: error,
          severityLevel: SeverityLevel.Error,
          properties: { ...properties, "error.type": error.name } as Record<string, string>
        });
      }
    }
  };
}

// Agent invocation
const agentSpan = startGenAiSpan("invoke_agent ResearchAssistant", {
  "gen_ai.operation.name": "invoke_agent",
  "gen_ai.provider.name": "azure.ai.openai",
  "gen_ai.agent.name": "ResearchAssistant",
  "gen_ai.agent.id": "asst_5j66UpCpwteGg4YSxUnt7lPY",
  "gen_ai.request.model": "gpt-4o-mini",
  "server.address": "myresource.openai.azure.com"
});

try {
  // Nested chat completion span
  const chat = startGenAiSpan("chat gpt-4o-mini", {
    "gen_ai.operation.name": "chat",
    "gen_ai.provider.name": "azure.ai.openai",
    "gen_ai.request.model": "gpt-4o-mini"
  });
  const res = await callAzureOpenAi(/* ... */);
  chat.end(true, {
    "gen_ai.response.model": res.model,
    "gen_ai.response.id": res.id,
    "gen_ai.response.finish_reasons": JSON.stringify(res.choices.map(c => c.finish_reason)),
    "gen_ai.usage.input_tokens": res.usage.prompt_tokens,
    "gen_ai.usage.output_tokens": res.usage.completion_tokens,
    "gen_ai.output.type": "text"
  });

  // Nested tool execution span
  const tool = startGenAiSpan("execute_tool getWeather", {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "getWeather",
    "gen_ai.tool.type": "function",
    "gen_ai.tool.call.id": "call_abc123"
  });
  const toolResult = await runGetWeather({ location: "SF" });
  tool.end(true);

  agentSpan.end(true, {
    "gen_ai.usage.input_tokens": res.usage.prompt_tokens,
    "gen_ai.usage.output_tokens": res.usage.completion_tokens
  });
} catch (err) {
  agentSpan.end(false, { "error.type": (err as Error).name }, err as Error);
}

浏览器的 traceparent 会自动附加到出站的 fetch（当 distributedTracingMode: 2 时），因此下游的 Azure OpenAI / 代理后端跨度会在 App Insights 中挂在同一个 operation_Id 下。

有关完整的属性参考、知名值以及内容捕获指南，请参阅 references/agent-traces.md。

KQL：在应用洞察中查询 GenAI 跟踪

dependencies
| where type == "GenAI"
| extend op   = tostring(customDimensions["gen_ai.operation.name"]),
         agent = tostring(customDimensions["gen_ai.agent.name"]),
         model = tostring(customDimensions["gen_ai.request.model"]),
         tin   = toint(customDimensions["gen_ai.usage.input_tokens"]),
         tout  = toint(customDimensions["gen_ai.usage.output_tokens"])
| summarize calls=count(), p95_ms=percentile(duration, 95),
            avg_in=avg(tin), avg_out=avg(tout) by op, agent, model, bin(timestamp, 5m)

请参阅 references/framework-extensions.md 获取完整的 React、React Native、Angular、Next.js 和 Vite 使用示例。

import { ApplicationInsights } from "@microsoft/applicationinsights-web";
import { ReactPlugin, withAITracking } from "@microsoft/applicationinsights-react-js";
import { createBrowserHistory } from "history";

const reactPlugin = new ReactPlugin();
const browserHistory = createBrowserHistory();

export const appInsights = new ApplicationInsights({
  config: {
    connectionString: import.meta.env.VITE_APPINSIGHTS_CONNECTION_STRING,
    extensions: [reactPlugin],
    extensionConfig: { [reactPlugin.identifier]: { history: browserHistory } }
  }
});
appInsights.loadAppInsights();

export const TrackedCheckout = withAITracking(reactPlugin, Checkout, "Checkout");

import { ApplicationInsights } from "@microsoft/applicationinsights-web";
import { ReactNativePlugin } from "@microsoft/applicationinsights-react-native";

const rnPlugin = new ReactNativePlugin();
const appInsights = new ApplicationInsights({
  config: {
    connectionString: process.env.EXPO_PUBLIC_APPINSIGHTS_CONNECTION_STRING,
    extensions: [rnPlugin],
    disableFetchTracking: false
  }
});
appInsights.loadAppInsights();

自动收集：通过 PerformanceTiming / PerformanceNavigationTiming 获取页面加载时间。要添加核心网页关键指标（Core Web Vitals）：

import { onCLS, onLCP, onINP, type Metric } from "web-vitals";

function send(m: Metric) {
  appInsights.trackMetric(
    { name: `web_vitals.${m.name.toLowerCase()}`, average: m.value },
    { rating: m.rating, navigationType: m.navigationType, id: m.id }
  );
}
onCLS(send); onLCP(send); onINP(send);

new ApplicationInsights({ config: {
  connectionString,
  isCookieUseDisabled: true,         // hard-disable all cookies
  cookieCfg: { enabled: true, domain: ".example.com", path: "/", expiry: 365 }
}});

appInsights.getCookieMgr().setEnabled(userGaveConsent);
appInsights.config.disableTelemetry = !userGaveConsent;

服务器端摄取采样（推荐）已在应用洞察资源上配置。SDK 端采样可以减少网络使用：

new ApplicationInsights({ config: { connectionString, samplingPercentage: 50 } });

通过遥测初始化器进行按类型采样：根据 item.baseType 使用 return false 丢弃。

SDK 使用 sendBeacon（默认 onunloadDisableBeacon: false）在 pagehide / unload 时刷新。对于单页应用（SPA），在破坏性切换（注销、强制重新加载）之前，也要调用 appInsights.flush()。

完整的 Web SDK 压缩后约为 110 KB（gzip 压缩后约 36 KB）。对于严格的预算，可以使用 Loader Script 路径，使 SDK 在关键路径之外异步加载，或者对未使用的插件进行 tree-shake。

import {
  ApplicationInsights,
  SeverityLevel,
  DistributedTracingModes,
  type IConfiguration,
  type IConfig,
  type ITelemetryItem,
  type ITelemetryPlugin,
  type ICustomProperties,
  type IPageViewTelemetry,
  type IEventTelemetry,
  type IExceptionTelemetry,
  type ITraceTelemetry,
  type IMetricTelemetry,
  type IDependencyTelemetry
} from "@microsoft/applicationinsights-web";

来源说明：本文内容整理自开源项目 agentic-awesome-skills（中文翻译版），遵循 CC BY 4.0（知识共享署名 4.0 国际）许可协议，此处作为中文资料整理分享，版权归原作者所有。

Applicationinsights Web Ts 实用指南

Instrument browser/web apps with the Application Insights JavaScript SDK (@microsoft/applicationinsights-web). Use for Real User Monitoring (RUM) — page views, clicks, AJAX/fetch dependencies, exceptions, custom events, and browser-side GenAI agent traces correlated to backend...

开发工具

前端

运维

本文提供Application Insights JavaScript SDK在浏览器端实现真实用户监控的完整指南，涵盖安装配置、核心API、点击分析、SPA路由跟踪及GenAI代理追踪，并通过W3C Trace Context实现与后端遥测关联，附带React/Angular集成示例与性能优化建议。

数据处理

身份验证

React Native

数据丢失

JavaScript

TypeScript 

服务器

路由器

路由

Agent

ReAct 

JSON

CDN免费试用


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

Applicationinsights Web Ts 实用指南

Applicationinsights Web Ts 实用指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐