适用于网页的 Application Insights

注意

我们将持续评估 OpenTelemetry 在浏览器方案中的可行性。 建议使用 Application Insights JavaScript SDK 以便可预见将来的情况。 它与 OpenTelemetry 分布式跟踪完全兼容。

了解网页或应用的性能和使用情况。 如果将 Application Insights 添加到页面脚本,可以获取页面加载和 AJAX 调用的时间,以及浏览器异常和 AJAX 失败的计数和详细信息。 还可以获取用户和会话计数。 所有这些遥测数据可按页面、客户端 OS 和浏览器版本、地理位置和其他维度细分。 可以针对失败计数或页面加载缓慢情况设置警报。 通过在 JavaScript 代码中插入跟踪调用,可以跟踪网页应用程序的不同功能的使用情况。

可以通过添加 JavaScript 的简短片段,在任何网页中使用 Application Insights。 Node.js 具有独立 SDK。 如果 Web 服务是 JavaASP.NET,则你可以将服务器端 SDK 与客户端 JavaScript SDK 结合使用,以全方面地了解应用的性能。

添加 JavaScript SDK

  1. 首先需要一个 Application Insights 资源。 如果你尚未获得资源和连接字符串,请遵照创建新资源的说明。
  2. 复制你要将 JavaScript 遥测数据发送到的资源(来自步骤 1)的连接字符串。 你需要将它添加到 Application Insights JavaScript SDK 的 connectionString 设置。
  3. 通过以下两个选项之一,将 Application Insights JavaScript SDK 添加到网页或应用:

警告

@microsoft/applicationinsights-web-basic - AISKULight 不支持使用连接字符串。

仅使用一种方法将 JavaScript SDK 添加到应用程序。 如果使用 npm 安装程序,请不要使用代码片段,反之亦然。

备注

npm 安装程序会将 JavaScript SDK 安装为项目的依赖项并启用 IntelliSense。 代码片段会在运行时提取 SDK。 两者都支持相同的功能。 需要更多自定义事件和配置的开发人员通常会选择 npm 安装程序。 希望快速启用线程 Web 分析的用户会选择代码片段。

基于 npm 的设置

通过 npm 安装。

npm i --save @microsoft/applicationinsights-web

注意

Typings 已包含在此包中,因此无需安装单独的 typings 包 。

import { ApplicationInsights } from '@microsoft/applicationinsights-web'

const appInsights = new ApplicationInsights({ config: {
  connectionString: 'Copy connection string from Application Insights Resource Overview'
  /* ...Other Configuration Options... */
} });
appInsights.loadAppInsights();
appInsights.trackPageView(); // Manually call trackPageView to establish the current user/session/pageview

基于代码片段的设置

如果应用不使用 npm,则可以通过直接使用 Application Insights 来检测网页:只需将此代码片段粘贴到每个页面的顶部即可。 最好是将它用作 <head> 节中的第一个脚本。 这样它便可以监视所有依赖项存在的任何潜在问题或任何 JavaScript 错误。 如果使用的是 Blazor Server 应用,请在文件 _Host.cshtml 的顶部 <head> 部分中添加代码片段。

从版本 2.5.5 开始,页面查看事件将包含一个新标记“ai.internal.snippet”,其中包含已识别的代码片段版本。 此功能有助于跟踪应用程序正在使用哪个版本的代码片段。

下面的当前代码片段为版本“5”。该版本在代码片段中编码为 sv:"#"GitHub 上也提供了当前版本

<script type="text/javascript">
!function(T,l,y){var S=T.location,k="script",D="connectionString",C="ingestionendpoint",I="disableExceptionTracking",E="ai.device.",b="toLowerCase",w="crossOrigin",N="POST",e="appInsightsSDK",t=y.name||"appInsights";(y.name||T[e])&&(T[e]=t);var n=T[t]||function(d){var g=!1,f=!1,m={initialize:!0,queue:[],sv:"5",version:2,config:d};function v(e,t){var n={},a="Browser";return n[E+"id"]=a[b](),n[E+"type"]=a,n["ai.operation.name"]=S&&S.pathname||"_unknown_",n["ai.internal.sdkVersion"]="javascript:snippet_"+(m.sv||m.version),{time:function(){var e=new Date;function t(e){var t=""+e;return 1===t.length&&(t="0"+t),t}return e.getUTCFullYear()+"-"+t(1+e.getUTCMonth())+"-"+t(e.getUTCDate())+"T"+t(e.getUTCHours())+":"+t(e.getUTCMinutes())+":"+t(e.getUTCSeconds())+"."+((e.getUTCMilliseconds()/1e3).toFixed(3)+"").slice(2,5)+"Z"}(),name:"Microsoft.ApplicationInsights."+e.replace(/-/g,"")+"."+t,sampleRate:100,tags:n,data:{baseData:{ver:2}}}}var h=d.url||y.src;if(h){function a(e){var t,n,a,i,r,o,s,c,u,p,l;g=!0,m.queue=[],f||(f=!0,t=h,s=function(){var e={},t=d.connectionString;if(t)for(var n=t.split(";"),a=0;a<n.length;a++){var i=n[a].split("=");2===i.length&&(e[i[0][b]()]=i[1])}if(!e[C]){var r=e.endpointsuffix,o=r?e.location:null;e[C]="https://"+(o?o+".":"")+"dc."+(r||"services.visualstudio.com")}return e}(),c=s[D]||d[D]||"",u=s[C],p=u?u+"/v2/track":d.endpointUrl,(l=[]).push((n="SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)",a=t,i=p,(o=(r=v(c,"Exception")).data).baseType="ExceptionData",o.baseData.exceptions=[{typeName:"SDKLoadFailed",message:n.replace(/\./g,"-"),hasFullStack:!1,stack:n+"\nSnippet failed to load ["+a+"] -- Telemetry is disabled\nHelp Link: https://go.microsoft.com/fwlink/?linkid=2128109\nHost: "+(S&&S.pathname||"_unknown_")+"\nEndpoint: "+i,parsedStack:[]}],r)),l.push(function(e,t,n,a){var i=v(c,"Message"),r=i.data;r.baseType="MessageData";var o=r.baseData;return o.message='AI (Internal): 99 message:"'+("SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details) ("+n+")").replace(/\"/g,"")+'"',o.properties={endpoint:a},i}(0,0,t,p)),function(e,t){if(JSON){var n=T.fetch;if(n&&!y.useXhr)n(t,{method:N,body:JSON.stringify(e),mode:"cors"});else if(XMLHttpRequest){var a=new XMLHttpRequest;a.open(N,t),a.setRequestHeader("Content-type","application/json"),a.send(JSON.stringify(e))}}}(l,p))}function i(e,t){f||setTimeout(function(){!t&&m.core||a()},500)}var e=function(){var n=l.createElement(k);n.src=h;var e=y[w];return!e&&""!==e||"undefined"==n[w]||(n[w]=e),n.onload=i,n.onerror=a,n.onreadystatechange=function(e,t){"loaded"!==n.readyState&&"complete"!==n.readyState||i(0,t)},n}();y.ld<0?l.getElementsByTagName("head")[0].appendChild(e):setTimeout(function(){l.getElementsByTagName(k)[0].parentNode.appendChild(e)},y.ld||0)}try{m.cookie=l.cookie}catch(p){}function t(e){for(;e.length;)!function(t){m[t]=function(){var e=arguments;g||m.queue.push(function(){m[t].apply(m,e)})}}(e.pop())}var n="track",r="TrackPage",o="TrackEvent";t([n+"Event",n+"PageView",n+"Exception",n+"Trace",n+"DependencyData",n+"Metric",n+"PageViewPerformance","start"+r,"stop"+r,"start"+o,"stop"+o,"addTelemetryInitializer","setAuthenticatedUserContext","clearAuthenticatedUserContext","flush"]),m.SeverityLevel={Verbose:0,Information:1,Warning:2,Error:3,Critical:4};var s=(d.extensionConfig||{}).ApplicationInsightsAnalytics||{};if(!0!==d[I]&&!0!==s[I]){var c="onerror";t(["_"+c]);var u=T[c];T[c]=function(e,t,n,a,i){var r=u&&u(e,t,n,a,i);return!0!==r&&m["_"+c]({message:e,url:t,lineNumber:n,columnNumber:a,error:i}),r},d.autoExceptionInstrumented=!0}return m}(y.cfg);function a(){y.onInit&&y.onInit(n)}(T[t]=n).queue&&0===n.queue.length?(n.queue.push(a),n.trackPageView({})):a()}(window,document,{
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js", // The SDK URL Source
// name: "appInsights", // Global SDK Instance name defaults to "appInsights" when not supplied
// ld: 0, // Defines the load delay (in ms) before attempting to load the sdk. -1 = block page load and add to head. (default) = 0ms load after timeout,
// useXhr: 1, // Use XHR instead of fetch to report failures (if available),
crossOrigin: "anonymous", // When supplied this will add the provided value as the cross origin attribute on the script tag
// onInit: null, // Once the application insights instance has loaded and initialized this callback function will be called with 1 argument -- the sdk instance (DO NOT ADD anything to the sdk.queue -- As they won't get called)
cfg: { // Application Insights Configuration
    connectionString: "Copy connection string from Application Insights Resource Overview"
    /* ...Other Configuration Options... */
}});
</script>

注意

为了提高可读性并减少可能的 JavaScript 错误,在上述代码片段的新行上列出了所有可能的配置选项。 如果不希望更改注释行的值,可以将其移除。

报告脚本加载失败

在从 CDN 加载 SDK 时,此版本的代码片段将检测并报告失败,在 Azure Monitor 门户中这种失败将显示为异常(在“失败”>“异常”>“浏览器”下)。 可以通过该异常洞察此类失败,以便知道应用程序未按预期方式报告遥测数据(或其他异常)。 此信号对于了解以下情况至关重要:由于未加载或初始化 SDK,因此缺少遥测数据,这可能导致:

  • 漏报用户使用或尝试使用站点的方式。
  • 缺少关于用户使用站点的方式的遥测数据。
  • 遗漏可能阻止用户成功使用站点的 JavaScript 错误。

有关此异常的信息,请参阅 SDK 加载失败故障排除页面。

将此失败作为门户异常进行报告时不会使用 Application Insights 配置中的 disableExceptionTracking 配置选项。 因此,如果发生此失败,则将始终通过代码片段进行报告,即使禁用了 window.onerror 支持也是如此。

Internet Explorer 8 或更早版本不支持报告 SDK 加载失败。 假设大多数环境都不仅仅是 Internet Explorer 8 或更低版本,此行为可以减少代码片段的缩小版大小。 如果你有此要求并且希望收到这些异常,则需要包括 fetch polyfill,或创建自己的代码片段版本,使其使用 XDomainRequest 而不是 XMLHttpRequest。 使用提供的代码片段源代码作为起点。

注意

如果你使用的是早期版本的代码片段,请更新到最新版本,以便收到以前未报告的问题。

代码片段配置选项

所有配置选项已移至脚本末尾。 这种放置方式可以避免意外造成 JavaScript 错误,这些错误不仅会导致 SDK 无法加载,还会禁用失败报告。

每个配置选项都会显示在新行上。 如果不希望覆盖作为 [可选] 列出的项的默认值,则可以移除该行以最大程度地减小所返回页面的大小。

此表中列出了可用配置选项。

名称 类型 说明
src 字符串 [必需] 要从中加载 SDK 的完整 URL。 此值用于动态添加的 <script /> 标记的“src”属性。 你可以使用公共 CDN 位置,也可以使用自己的私有托管位置。
name 字符串 [可选] 已初始化的 SDK 的全局名称,默认值为 appInsights。 因此 window.appInsights 将是对已初始化实例的引用。 如果提供一个名称值或上一个实例似乎是通过全局名称 appInsightsSDK 分配的,则此名称值也将在全局命名空间中定义为 window.appInsightsSDK=<name value>。 SDK 初始化代码使用此引用来确保它初始化和更新的是正确的代码片段主干和代理方法。
ld 毫秒数 [可选] 定义在尝试加载 SDK 之前要等待的加载延迟。 默认值为 0 毫秒。 任何负值都表示将立即向页面的 <head> 区域添加脚本标记。 然后在加载脚本或失败之前阻止页面加载事件。
useXhr 布尔 [可选] 此设置仅用于报告 SDK 加载失败。 报告将首先尝试使用 fetch()(如果可用),然后回退到 XHR。 将此值设置为 true 即可绕过提取检查。 仅当在提取将无法发送失败事件的环境中使用应用程序时,才需要使用此值。
crossOrigin 字符串 [可选] 通过包含此设置,添加以下载 SDK 的脚本标记将包含带有此字符串值的 crossOrigin 属性。 如果未定义(默认值),则不添加 crossOrigin 属性。 未定义建议值(默认值);"";或“anonymous”。如需了解所有有效值,请参阅 HTML 属性:crossorigin 文档。
cfg 对象 [必需] 初始化期间传递到 Application Insights SDK 的配置。

连接字符串设置

注意

对检测密钥引入的支持将于 2025 年 3 月 31 日结束。 检测密钥引入功能将会继续工作,但我们将不再为该功能提供更新或支持。 转换为连接字符串,以利用新功能

import { ApplicationInsights } from '@microsoft/applicationinsights-web'

const appInsights = new ApplicationInsights({ config: {
  connectionString: 'YOUR_CONNECTION_STRING_GOES_HERE'
  /* ...Other Configuration Options... */
} });
appInsights.loadAppInsights();
appInsights.trackPageView();

将遥测数据发送到 Azure 门户

Application Insights JavaScript SDK 默认自动收集许多遥测项,它们有助于确定应用程序的运行状况和基础用户体验。

这些遥测数据包括:

  • 应用中未捕获到的异常,包括以下相关信息:
    • 堆栈跟踪。
    • 异常详细信息和错误随附的消息。
    • 错误的行号和列号。
    • 引发错误的 URL。
  • 应用发出的网络依赖项请求:XHR 和 Fetch(默认已禁用提取集合)请求包括以下相关信息:
    • 依赖项源的 URL。
    • 用于请求依赖项的命令和方法。
    • 请求持续时间。
    • 请求的结果代码和成功状态。
    • 发出请求的用户的 ID(如果有)。
    • 发出请求的关联上下文(如果有)。
  • 用户信息(例如位置、网络、IP)
  • 设备信息(例如,浏览器、OS、版本、语言、型号)
  • 会话信息

遥测初始化表达式

遥测初始化表达式用于在从用户浏览器发送收集的遥测内容之前先对其进行修改。 它们还可用于返回 false 以阻止发送某些遥测数据。 可将多个遥测初始化表达式添加到 Application Insights 实例。 它们会按添加顺序执行。

addTelemetryInitializer 的输入参数是一个回调,该回调采用 ITelemetryItem 作为参数,并返回 booleanvoid。 如果返回 false,则不发送遥测项,否则将继续处理下一个遥测初始化表达式(如果有),或者将遥测项发送到遥测集合终结点。

使用遥测初始化表达式的示例:

var telemetryInitializer = (envelope) => {
  envelope.data.someField = 'This item passed through my telemetry initializer';
};
appInsights.addTelemetryInitializer(telemetryInitializer);
appInsights.trackTrace({message: 'This message will use a telemetry initializer'});

appInsights.addTelemetryInitializer(() => false); // Nothing is sent after this is executed
appInsights.trackTrace({message: 'this message will not be sent'}); // Not sent

配置

大多数配置字段的命名都可默认为 false。 除 connectionString 以外的所有字段都是可选的。

名称 说明 默认
connectionString 必需
从 Azure 门户获取的连接字符串。
string
NULL
accountId 可选的帐户 ID(如果应用将用户分组到帐户中)。 不允许使用空格、逗号、分号、等号或竖线。 string
NULL
sessionRenewalMs 如果用户处于非活动状态有这么长的时间(以毫秒为单位),则会记录会话。 numeric
1800000
(30 分钟)
sessionExpirationMs 如果会话持续了这么长的时间(以毫秒为单位),则会记录会话。 numeric
86400000
(24 小时)
maxBatchSizeInBytes 遥测批的最大大小。 如果某个批超过此限制,则立即发送此批,并启动新批。 numeric
10000
maxBatchInterval 发送前要批处理遥测数据的时间长短(毫秒)。 numeric
15000
disable​ExceptionTracking 如果为 true,则不自动收集异常。 boolean
false
disableTelemetry 如果为 true,则不收集或发送遥测数据。 boolean
false
enableDebug 如果为 true,则不管 SDK 日志记录设置如何,内部调试数据都将引发为异常,而不是记录这些数据。 默认值为 false。
注意:如果启用此设置,每当发生内部错误时,都会导致丢弃遥测数据。 此设置可能有助于快速识别 SDK 的配置或用法问题。 如果你不希望在调试时丢失遥测数据,请考虑使用 loggingLevelConsoleloggingLevelTelemetry,而不是 enableDebug
boolean
false
loggingLevelConsole 内部 Application Insights 错误记录到控制台。
0:关闭,
1:仅限严重错误,
2:所有内容(错误和警告)
numeric
0
loggingLevelTelemetry 内部 Application Insights 错误作为遥测数据发送。
0:关闭,
1:仅限严重错误,
2:所有内容(错误和警告)
numeric
1
diagnosticLogInterval 内部日志记录队列的(内部)轮询间隔(以毫秒为单位)。 numeric
10000
samplingPercentage 要发送的事件百分比。 默认值为 100,表示发送所有事件。 如果你希望避免大型应用程序达到数据上限,请设置此选项。 numeric
100
autoTrackPageVisitTime 如果为 true,则对于页面视图,将跟踪上一个检测的页面的查看时间并将其作为遥测数据发送,同时,为当前的页面视图启动新的计时器。 它作为 milliseconds 中名为 PageVisitTime 的自定义指标发送,通过 Date now() 函数(如果可用)进行计算,并在 now() 不可用的情况下(Internet Explorer 8 或更低版本)回退到 (new Date()).getTime()。 默认值为 false。 boolean
false
disableAjaxTracking 如果为 true,则不自动收集 Ajax 调用。 boolean
false
disableFetchTracking 如果为 true,则不自动收集 Fetch 请求。 boolean
false
overridePageViewDuration 如果为 true,则在调用 trackPageView 时,trackPageView 的默认行为将更改为记录页面视图持续时间间隔的结束时间。 如果为 false 且未为 trackPageView 提供自定义持续时间,则会使用导航计时 API 计算页面视图性能。 boolean
maxAjaxCallsPerView 默认值为 500,可控制每个页面视图将监视多少个 Ajax 调用。 设置为 -1 可监视页面上的所有(无限制)Ajax 调用。 numeric
500
disableDataLossAnalysis 如果为 false,则对于尚未发送的项,启动时将检查内部遥测发送方缓冲区。 boolean
disable​CorrelationHeaders 如果为 false,则 SDK 会将两个标头(Request-IdRequest-Context)添加到所有依赖项请求,以将其关联到服务器端上的对应请求。 boolean
false
correlationHeader​ExcludedDomains 禁用特定域的关联标头。 string[]
undefined
correlationHeader​ExcludePatterns 使用正则表达式禁用关联标头。 regex[]
undefined
correlationHeader​Domains 启用特定域的关联标头。 string[]
undefined
disableFlush​OnBeforeUnload 如果为 true,则触发 onBeforeUnload 事件时不会调用 flush 方法。 boolean
false
enableSessionStorageBuffer 如果为 true,则会将包含所有未发送的遥测数据的缓冲区存储在会话存储中。 加载页面时会还原该缓冲区。 boolean
cookieCfg 启用 Cookie 使用的默认设置。 有关完整默认值,请参阅 ICookieCfgConfig 设置。 ICookieCfgConfig
(自 2.6.0 起)
undefined
isCookieUseDisabled
disableCookiesUsage
如果为 true,则 SDK 不会存储或读取 Cookie 中的任何数据。 禁用用户和会话 Cookie,令使用情况边栏选项卡和体验无效。 弃用了 isCookieUseDisable 以支持 disableCookiesUsage。 如果同时提供两者,则 disableCookiesUsage 优先。
(自 v2.6.0 起)如果还定义了 cookieCfg.enabled,则其优先级高于这些值。 通过 core.getCookieMgr().setEnabled(true) 进行初始化后,可以重新启用 Cookie 使用。
cookieCfg.enabled 的别名
false
cookieDomain 自定义 Cookie 域。 如果你要跨子域共享 Application Insights Cookie,此选项会有帮助。
(自 v2.6.0 起)如果定义了 cookieCfg.domain,则其优先级高于此值。
cookieCfg.domain 的别名
null
cookiePath 自定义 cookie 路径。 如果你要在应用程序网关后共享 Application Insights Cookie,此选项会有帮助。
如果定义了 cookieCfg.path,则其优先级高于此值。
cookieCfg.path 的别名
(自 2.6.0 起)
null
isRetryDisabled 如果为 false,则出现代码 206(部分成功)、408(超时)、429(请求过多)、500(内部服务器错误)、503(服务不可用)和 0(脱机,仅当已检测到此状态时)时会重试。 boolean
false
isStorageUseDisabled 如果为 true,则 SDK 不会存储或读取本地和会话存储中的任何数据。 boolean
false
isBeaconApiDisabled 如果为 false,则 SDK 将使用信标 API 发送所有遥测数据。 boolean
onunloadDisableBeacon 选项卡关闭时,SDK 将使用信标 API 发送所有剩余的遥测。 boolean
false
sdkExtension 设置 SDK 扩展名。 仅允许使用字母字符。 扩展名将添加为“ai.internal.sdkVersion”标记的前缀(例如“ext_javascript:2.0.0”)。 string
NULL
isBrowserLink​TrackingEnabled 如果为 true,则 SDK 将跟踪所有浏览器链接请求。 boolean
false
appId appId 用于在客户端上发生的 AJAX 依赖项与服务器端请求之间进行关联。 启用信标 API 后,无法自动使用 appId,但可以在配置中手动设置它。 string
NULL
enable​CorsCorrelation 如果为 true,则 SDK 会将两个标头(Request-IdRequest-Context)添加到所有 CORS 请求,以将传出的 AJAX 依赖项关联到服务器端上的对应请求。 boolean
false
namePrefix 一个可选值,用作 localStorage 和 Cookie 名称的名称后缀。 字符串
undefined
enable​AutoRoute​Tracking 自动跟踪单页应用程序中的路由更改。 如果为 true,则每次更改路由都会将一个新的页面视图发送到 Application Insights。 哈希路由更改 (example.com/foo#bar) 也会记录为新的页面视图。 boolean
false
enableRequest​HeaderTracking 如果为 true,则跟踪 AJAX 和 Fetch 请求标头。 boolean
false
enableResponse​HeaderTracking 如果为 true,则跟踪 AJAX 和 Fetch 请求响应标头。 boolean
false
distributedTracingMode 设置分布式跟踪模式。 如果设置了 AI_AND_W3C 模式或 W3C 模式,则将生成 W3C 跟踪上下文标头 (traceparent/tracestate),并将其包含在所有传出请求中。 提供 AI_AND_W3C 是为了与任何旧版 Application Insights 检测服务向后兼容。 请参阅此网站中的示例。 DistributedTracingModes
numeric
(自 v2.6.0 起)DistributedTracingModes.AI_AND_W3C
(v 2.5.11 或更早版本)DistributedTracingModes.AI
enable​AjaxErrorStatusText 如果为 true,则在 AJAX 请求失败时包含依赖关系事件中的响应错误数据文本。 boolean
false
enable​AjaxPerfTracking 一个标记,用于执行以下操作:查找其他浏览器 window.performance 计时,并将其包含在报告的 ajax(XHR 和 fetch)的报告指标中。 boolean
false
maxAjaxPerf​LookupAttempts 查找 window.performance 计时的最大次数(如果适用)。 有时需要此选项,因为并非所有浏览器都会在报告 XHR 请求结束之前填充 window.performance。 对于提取请求,此信息是在请求完成后添加的。 numeric
3
ajaxPerfLookupDelay 重新尝试为 ajax 请求查找 window.performance 计时所需等待的时间量。 时间以毫秒为单位,并直接传递给 setTimeout()。 numeric
25 毫秒
enableUnhandled​PromiseRejection​Tracking 如果为 true,则将自动收集未处理的拒绝承诺并报告为 JavaScript 错误。 如果 disableExceptionTracking 为 true(不跟踪异常),则将忽略配置值且不会报告未处理的拒绝承诺。 boolean
false
enablePerfMgr 启用时(为 true 时)将为已检测的代码创建本地 perfEvents 以发出 perfEvents(通过 doPerf() 帮助程序)。 此选项可用于根据使用情况识别 SDK 中的性能问题,或者选择性地在你自己的已检测代码中识别性能问题。 基本文档中提供了详细信息。 自 v2.5.7 起 boolean
false
perfEvtsSendAll 如果已启用 enablePerfMgr 且 IPerfManager 触发了 INotificationManager.perfEvent(),此标志会确定是为所有事件触发事件并发送到所有侦听器(为 true 时),还是仅针对父级事件触发事件(为 false 时,<默认值>)。
父级 IPerfEvent 事件在创建时没有其他 IPerfEvent 仍在运行,且其“父级”属性不为 NULL 或未定义状态。 自 v2.5.7 起
boolean
false
idLength 用于生成新的随机会话和用户 ID 值的默认长度。 默认值为 22。 以前的默认值为 5(v2.5.8 或更低版本)。 如果需要保留以前的最大长度,则应将此值设置为 5。 numeric
22

从版本 2.6.0 开始,Cookie 管理功能现在可直接在实例中使用,并且可以在初始化后禁用和重新启用。

如果在初始化期间通过 disableCookiesUsagecookieCfg.enabled 配置禁用了该功能,现在可以使用 ICookieMgrsetEnabled 函数重新启用。

基于实例的 Cookie 管理还替代了 disableCookies()setCookie(...)getCookie(...)deleteCookie(...) 之前的 CoreUtils 全局函数。 若要从版本 2.6.0 中引入的摇树增强功能中受益,应不再使用全局函数。

ICookieMgrConfig

基于实例的 Cookie 管理的 Cookie 配置,添加在版本 2.6.0 中。

名称 说明 类型和默认值
enabled 一个布尔,指示当前实例是否让 SDK 使用 Cookie。 如果为 false,则此配置所初始化的 SDK 实例将不会存储或读取 Cookie 中的任何数据。 boolean
自定义 Cookie 域。如果你要跨子域共享 Application Insights Cookie,此选项会有帮助。 如果未提供,则使用根 cookieDomain 值中的值。 string
NULL
path 指定要用于 Cookie 的路径。 如果未提供,将使用根 cookiePath 值中的任意值。 字符串
/
getCookie 用于提取命名 Cookie 值的函数。 如果未提供,则使用内部 cookie 解析/缓存。 (name: string) => string
null
setCookie 用于设置具有指定值的命名 Cookie 的函数。 仅在添加或更新 Cookie 时调用。 (name: string, value: string) => void
null
delCookie 用于删除具有指定值的命名 Cookie 的函数,与 setCookie 分离,从而无需分析值以确定是否添加或删除 Cookie。 如果未提供,则使用内部 cookie 解析/缓存。 (name: string, value: string) => void
Null

启用“页面访问时间”跟踪

通过设置 autoTrackPageVisitTime: true,跟踪用户在每个页面上花费的时间(以毫秒计)。 在每个新的页面视图上,用户在上一页花费的时间将作为名为 PageVisitTime 的自定义指标发送。 此自定义指标可在指标资源管理器中作为基于日志的指标查看。

启用分布式跟踪

关联功能会生成并发送启用分布式跟踪的数据,并为应用程序映射端到端事务查看和其他诊断工具提供支持。

在 JavaScript 中,默认情况下关联处于关闭状态,以便最大程度地减少默认发送的遥测数据。 以下示例显示了用于启用关联的标准配置选项。

以下示例代码显示了启用关联所需的配置。

  • 代码片段
  • npm
// excerpt of the config section of the JavaScript SDK snippet with correlation
// between client-side AJAX and server requests enabled.
cfg: { // Application Insights Configuration
    instrumentationKey: "YOUR_INSTRUMENTATION_KEY_GOES_HERE"
    connectionString: "Copy connection string from Application Insights Resource Overview"
    enableCorsCorrelation: true,
    enableRequestHeaderTracking: true,
    enableResponseHeaderTracking: true,
    correlationHeaderExcludedDomains: ['*.queue.core.chinacloudapi.cn']
    /* ...Other Configuration Options... */
}});
</script>

注意

有两种分布式跟踪模式/协议:AI(经典)和 W3C TraceContext(新)。 在版本 2.6.0 及更高版本中,它们均默认处于启用状态。 对于早期版本,用户需要显式选择加入 W3C 模式

路由跟踪

默认情况下,此 SDK 不会处理单页应用程序中发生的基于状态的路由更改。 若要为单页应用程序启用自动路由更改跟踪,可将 enableAutoRouteTracking: true 添加到设置配置。

单页应用程序

对于单页应用程序,请参阅插件文档以了解特定于插件的指导。

插件
React
React Native
Angular
单击“分析自动收集”

高级关联

首次加载页面且 SDK 尚未完全初始化时,无法为第一个请求生成操作 ID。 因此,在 SDK 完全初始化之前,分布式跟踪是不完全的。 若要解决此问题,可以在返回的 HTML 页面上包含动态 JavaScript。 在初始化期间,SDK 将使用回调函数以追溯方式从 serverside 拉取操作 ID,并在其中填充 clientside

  • 代码片段
  • npm

下面是如何使用 Razor 创建动态 JavaScript 的示例。

<script>
!function(T,l,y){<removed snippet code>,{
    src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js", // The SDK URL Source
    onInit: function(appInsights) {
        var serverId = "@this.Context.GetRequestTelemetry().Context.Operation.Id";
        appInsights.context.telemetryTrace.parentID = serverId;
    },
    cfg: { // Application Insights Configuration
        instrumentationKey: "YOUR_INSTRUMENTATION_KEY_GOES_HERE"
    }});
</script>

注意

应用程序 UX 尚未优化为显示这些“第一跃点”高级分布式跟踪方案。 数据将提供到请求表中以用于查询和诊断。

扩展

扩展
React
React Native
Angular
单击“分析自动收集”

浏览浏览器/客户端数据

可以转到“指标”并添加你感兴趣的各个指标,来查看浏览器/客户端数据。

显示 Application Insights“指标”页的屏幕截图,其中显示了 Web 应用程序指标数据的图形显示。

还可以通过门户中的浏览器体验查看 JavaScript SDK 中的数据。

选择“浏览器”,然后选择“失败”或“性能”。

显示 Application Insights“浏览器”页的屏幕截图,其中显示了如何将浏览器故障或浏览器性能添加到可以为 Web 应用程序查看的指标中。

性能

显示 Application Insights“性能”页的屏幕截图,其中显示了 Web 应用程序操作指标的图形显示。

依赖项

显示 Application Insights“性能”页的屏幕截图,其中显示了 Web 应用程序依赖项指标的图形显示。

分析

若要查询 JavaScript SDK 收集的遥测数据,请选择“在日志(分析)中查看”按钮。 如果添加 client_Type == "Browser"where 语句,则只会看到来自 JavaScript SDK 的数据。 其他 SDK 收集的任何服务器端遥测数据将被排除。

// average pageView duration by name
let timeGrain=5m;
let dataset=pageViews
// additional filters can be applied here
| where timestamp > ago(1d)
| where client_Type == "Browser" ;
// calculate average pageView duration for all pageViews
dataset
| summarize avg(duration) by bin(timestamp, timeGrain)
| extend pageView='Overall'
// render result in a chart
| render timechart

源映射支持

可以在 Azure 门户中取消缩小异常遥测的已缩小调用堆栈。 “异常详细信息”面板中的所有现有集成将适用于最近取消缩小的调用堆栈。

可以将 Application Insights 资源链接到自己的 Azure Blob 存储容器,以便自动取消缩小调用堆栈。 若要开始,请参阅自动源映射支持

拖放

  1. 请在 Azure 门户中选择一个异常遥测项,以查看其“端到端事务详细信息”。

  2. 确定哪些源映射对应于此调用堆栈。 源映射必须与堆栈帧的源文件相匹配,但后缀为 .map

  3. 将源映射拖动到 Azure 门户中的调用堆栈上。

    此动画图像显示了如何将源映射文件从生成文件夹拖放到 Azure 门户的“调用堆栈”窗口中。

Application Insights Web 基本版

若要获得精简的体验,可以改为安装基本版 Application Insights:

npm i --save @microsoft/applicationinsights-web-basic

此版本附带最少数量的功能,你可以根据自己的需求对其进行构建。 例如,它不执行自动收集(例如未捕获的异常和 AJAX)。 此版本不包含用于发送某些遥测类型的 API(例如 trackTracetrackException)。 因此你需要提供自己的包装器。 提供的唯一 API 是 track此处提供了一个示例。

示例

如需查看可运行的示例,请参阅 Application Insights JavaScript SDK 示例

从旧版 Application Insights 升级

SDK V2 版本中的重大更改:

  • 为了让用户生成更好的 API 签名,某些 API 调用(例如 trackPageView 和 trackException)已更新。 不支持在 Internet Explorer 8 和早期版本的浏览器中运行。

  • 由于数据架构更新,遥测信封的字段名称和结构已更改。

  • 已将 context.operation 转移到 context.telemetryTrace。 此外还更改了一些字段 (operation.id -->telemetryTrace.traceID)。

    若要手动刷新当前页面视图 ID(例如,在单页应用程序中),请使用 appInsights.properties.context.telemetryTrace.traceID = Microsoft.ApplicationInsights.Telemetry.Util.generateW3CId()

    注意

    为了使跟踪 ID 独一无二,以前使用 Util.newId(),现在使用 Util.generateW3CId()。 二者最终都会成为操作 ID。

如果你正在使用最新的 Application Insights PRODUCTION SDK (1.0.20),并想要查看新 SDK 是否可在运行时中正常工作,请根据当前的 SDK 加载方案更新 URL。

  • 通过 CDN 方案下载:更新当前用于指向以下 URL 的代码片段:

    "https://js.monitor.azure.com/scripts/b/ai.2.min.js"
    
  • npm 方案:调用 downloadAndSetup 以从 CDN 下载完整的 ApplicationInsights 脚本,并使用连接字符串将其初始化:

    appInsights.downloadAndSetup({
       connectionString: "Copy connection string from Application Insights Resource Overview",
       url: "https://js.monitor.azure.com/scripts/b/ai.2.min.jss"
       });
    

在内部环境中进行测试,以验证是否可按预期方式监视遥测。 如果一切正常,请相应地将 API 签名更新为 SDK v2,并部署到生产环境中。

SDK 性能/开销

经过 gzip 压缩后只有 36 KB,只需大约 15 毫秒即可完成初始化,Application Insights 在网站中的加载时间可忽略不计。 使用此代码片段时,很快就能加载极少量的库组件。 同时,整个脚本将在后台下载。

从 CDN 下载脚本时,页面的所有跟踪将会排队。 在下载的脚本以异步方式完成初始化后,将会跟踪已排队的所有事件。 因此,在页面的整个生命周期内,你都不会丢失任何遥测数据。 此设置过程可为页面提供一个无缝分析系统,而用户察觉不到该系统。

摘要:

  • npm 版本
  • gzip 压缩大小
  • 总初始化时间为 15 毫秒
  • 在页面的整个生命周期内都不会失去跟踪

浏览器支持

Chrome Firefox IE Opera Safari
Chrome 最新版 ✔ Firefox 最新版 ✔ IE 9+ 和 Microsoft Edge ✔
IE 8- 兼容
Opera 最新版 ✔ Safari 最新版 ✔

ES3/Internet Explorer 8 兼容性

我们需要确保此 SDK 继续“工作”,并且在由旧版浏览器加载时不会中断 JavaScript 执行。 不支持早期的浏览器是理想做法,但有众多的大客户无法控制其用户选择使用的浏览器。

这种陈述并不意味着我们仅支持最少量的常用功能集。 我们需要保持 ES3 代码的兼容性。 在添加新功能时,需要以不干扰 ES3 JavaScript 分析的方式将其添加为可选功能。

有关 Internet Explorer 8 支持的完整详细信息,请参阅 GitHub。

开源 SDK

Application Insights JavaScript SDK 是开放源代码。 若要查看源代码或是对项目做贡献,请参阅官方 GitHub 存储库

有关最新的更新和 bug 修复,请参阅发行说明

疑难解答

此部分可帮助你对常见问题进行故障排除。

收到错误消息“无法获取 Request-Context 关联标头,因为它可能不包含在响应中或无法访问”

correlationHeaderExcludedDomains 配置属性是一个排除列表,用于禁用特定域的关联标头。 如果包含这些标头会导致请求失败或由于第三方服务器配置原因而无法发送请求,则此选项很有用。 此属性支持通配符。 例如 *.queue.core.chinacloudapi.cn,如上面的代码示例所示。 应避免将应用程序域添加到此属性,因为它会阻止 SDK 将所需的分布式跟踪 Request-IdRequest-Contexttraceparent 标头包含为请求的一部分。

不确定如何更新第三方服务器配置

服务器端需要能够接受与所示的这些标头的连接。 根据服务器端的 Access-Control-Allow-Headers 配置,通常你需要通过手动添加 Request-IdRequest-Contexttraceparent(W3C 分布式标头)来扩展服务器端列表。

Access-Control-Allow-Headers:Request-IdtraceparentRequest-Context<your header>

从 Application Insights JavaScript SDK 收到重复的遥测数据

如果 SDK 以递归方式报告关联,请启用 excludeRequestFromAutoTrackingPatterns 配置设置以排除重复数据。 使用连接字符串时可能会出现这种情况。 配置设置的语法为 excludeRequestFromAutoTrackingPatterns: [<endpointUrl>]

测试应用程序主机与引入服务之间的连接性

Application Insights SDK 和代理发送遥测,将其作为 REST 调用引入到引入终结点。 可以使用原始 REST 客户端通过 PowerShell 或使用 curl 命令,测试从 Web 服务器或应用程序主机计算机到引入服务终结点的连接。 请参阅排查 Azure Monitor Application Insights 中缺失应用程序遥测的问题

后续步骤