启用 Azure Monitor Application Insights 真实用户监视

Azure Monitor Application Insights JavaScript SDK 收集使用情况数据,使你能够监视和分析 JavaScript Web 应用程序的性能。 这通常称为真实用户监视或 RUM。

Application Insights JavaScript SDK 具有一个基本 SDK 和多个插件,用于提供更多功能。

Conceptual diagram that shows the Application Insights JavaScript SDK, its plugins/extensions, and their relationship to each other.

默认情况下,收集页面浏览量。 但如果想在默认情况下收集点击量,请考虑添加“点击分析自动收集插件”:

  • 如果要添加框架扩展(可以在按照下面的步骤开始操作后添加),则可以选择在添加框架扩展时添加 Click Analytics。
  • 如果不添加框架扩展,请在按照步骤开始操作后添加“点击分析”插件

我们提供用于调试/测试的调试插件和性能插件。 在极少数情况下,可以通过添加自定义插件来生成自己的扩展。

先决条件

入门

按照本节中的步骤,使用 Application Insights JavaScript SDK 检测应用。

提示

好消息! 我们让启用 JavaScript 变得更加简单。 查看根据配置提供 JavaScript (Web) SDK 加载程序脚本注入的位置!

添加 JavaScript SDK 代码

可使用两种方法通过 Application Insights JavaScript SDK 来添加代码以启用 Application Insights:

方法 什么时候使用此方法?
JavaScript (Web) SDK 加载程序脚本 对于大多数客户,建议使用 JavaScript (Web) SDK 加载程序脚本,因为永远不必更新 SDK,并且可以自动获得最新更新。 还可以控制将 Application Insights JavaScript SDK 添加到哪些页面。
npm 包 希望将 SDK 引入代码并启用 IntelliSense。 只有需要更多自定义事件和配置的开发人员才需要使用此选项。 如果计划使用 React、React Native 或 Angular Framework 扩展,则需要此方法。
  1. 将 JavaScript (Web) SDK 加载程序脚本粘贴到要为其启用 Application Insights 的每个页面的顶部。

    最好是将其添加为 <head> 部分中的第一个脚本,以便它可以监视所有依赖项存在的任何潜在问题。

    如果检测到 Internet Explorer 8,则会自动加载 JavaScript SDK v2.x。

    <script type="text/javascript">
    !(function (cfg){function e(){cfg.onInit&&cfg.onInit(i)}var S,u,D,t,n,i,C=window,x=document,w=C.location,I="script",b="ingestionendpoint",E="disableExceptionTracking",A="ai.device.";"instrumentationKey"[S="toLowerCase"](),u="crossOrigin",D="POST",t="appInsightsSDK",n=cfg.name||"appInsights",(cfg.name||C[t])&&(C[t]=n),i=C[n]||function(l){var d=!1,g=!1,f={initialize:!0,queue:[],sv:"7",version:2,config:l};function m(e,t){var n={},i="Browser";function a(e){e=""+e;return 1===e.length?"0"+e:e}return n[A+"id"]=i[S](),n[A+"type"]=i,n["ai.operation.name"]=w&&w.pathname||"_unknown_",n["ai.internal.sdkVersion"]="javascript:snippet_"+(f.sv||f.version),{time:(i=new Date).getUTCFullYear()+"-"+a(1+i.getUTCMonth())+"-"+a(i.getUTCDate())+"T"+a(i.getUTCHours())+":"+a(i.getUTCMinutes())+":"+a(i.getUTCSeconds())+"."+(i.getUTCMilliseconds()/1e3).toFixed(3).slice(2,5)+"Z",iKey:e,name:"Microsoft.ApplicationInsights."+e.replace(/-/g,"")+"."+t,sampleRate:100,tags:n,data:{baseData:{ver:2}},ver:4,seq:"1",aiDataContract:undefined}}var h=-1,v=0,y=["js.monitor.azure.com","js.cdn.applicationinsights.io","js.cdn.monitor.azure.com","js0.cdn.applicationinsights.io","js0.cdn.monitor.azure.com","js2.cdn.applicationinsights.io","js2.cdn.monitor.azure.com","az416426.vo.msecnd.net"],k=l.url||cfg.src;if(k){if((n=navigator)&&(~(n=(n.userAgent||"").toLowerCase()).indexOf("msie")||~n.indexOf("trident/"))&&~k.indexOf("ai.3")&&(k=k.replace(/(\/)(ai\.3\.)([^\d]*)$/,function(e,t,n){return t+"ai.2"+n})),!1!==cfg.cr)for(var e=0;e<y.length;e++)if(0<k.indexOf(y[e])){h=e;break}var i=function(e){var a,t,n,i,o,r,s,c,p,u;f.queue=[],g||(0<=h&&v+1<y.length?(a=(h+v+1)%y.length,T(k.replace(/^(.*\/\/)([\w\.]*)(\/.*)$/,function(e,t,n,i){return t+y[a]+i})),v+=1):(d=g=!0,o=k,c=(p=function(){var e,t={},n=l.connectionString;if(n)for(var i=n.split(";"),a=0;a<i.length;a++){var o=i[a].split("=");2===o.length&&(t[o[0][S]()]=o[1])}return t[b]||(e=(n=t.endpointsuffix)?t.location:null,t[b]="https://"+(e?e+".":"")+"dc."+(n||"services.visualstudio.com")),t}()).instrumentationkey||l.instrumentationKey||"",p=(p=p[b])?p+"/v2/track":l.endpointUrl,(u=[]).push((t="SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)",n=o,r=p,(s=(i=m(c,"Exception")).data).baseType="ExceptionData",s.baseData.exceptions=[{typeName:"SDKLoadFailed",message:t.replace(/\./g,"-"),hasFullStack:!1,stack:t+"\nSnippet failed to load ["+n+"] -- Telemetry is disabled\nHelp Link: https://go.microsoft.com/fwlink/?linkid=2128109\nHost: "+(w&&w.pathname||"_unknown_")+"\nEndpoint: "+r,parsedStack:[]}],i)),u.push((s=o,t=p,(r=(n=m(c,"Message")).data).baseType="MessageData",(i=r.baseData).message='AI (Internal): 99 message:"'+("SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details) ("+s+")").replace(/\"/g,"")+'"',i.properties={endpoint:t},n)),o=u,c=p,JSON&&((r=C.fetch)&&!cfg.useXhr?r(c,{method:D,body:JSON.stringify(o),mode:"cors"}):XMLHttpRequest&&((s=new XMLHttpRequest).open(D,c),s.setRequestHeader("Content-type","application/json"),s.send(JSON.stringify(o))))))},a=function(e,t){g||setTimeout(function(){!t&&f.core||i()},500),d=!1},T=function(e){var n=x.createElement(I),e=(n.src=e,cfg[u]);return!e&&""!==e||"undefined"==n[u]||(n[u]=e),n.onload=a,n.onerror=i,n.onreadystatechange=function(e,t){"loaded"!==n.readyState&&"complete"!==n.readyState||a(0,t)},cfg.ld&&cfg.ld<0?x.getElementsByTagName("head")[0].appendChild(n):setTimeout(function(){x.getElementsByTagName(I)[0].parentNode.appendChild(n)},cfg.ld||0),n};T(k)}try{f.cookie=x.cookie}catch(p){}function t(e){for(;e.length;)!function(t){f[t]=function(){var e=arguments;d||f.queue.push(function(){f[t].apply(f,e)})}}(e.pop())}var r,s,n="track",o="TrackPage",c="TrackEvent",n=(t([n+"Event",n+"PageView",n+"Exception",n+"Trace",n+"DependencyData",n+"Metric",n+"PageViewPerformance","start"+o,"stop"+o,"start"+c,"stop"+c,"addTelemetryInitializer","setAuthenticatedUserContext","clearAuthenticatedUserContext","flush"]),f.SeverityLevel={Verbose:0,Information:1,Warning:2,Error:3,Critical:4},(l.extensionConfig||{}).ApplicationInsightsAnalytics||{});return!0!==l[E]&&!0!==n[E]&&(t(["_"+(r="onerror")]),s=C[r],C[r]=function(e,t,n,i,a){var o=s&&s(e,t,n,i,a);return!0!==o&&f["_"+r]({message:e,url:t,lineNumber:n,columnNumber:i,error:a,evt:C.event}),o},l.autoExceptionInstrumented=!0),f}(cfg.cfg),(C[n]=i).queue&&0===i.queue.length?(i.queue.push(e),i.trackPageView({})):e();})({
    src: "https://js.monitor.azure.com/scripts/b/ai.3.gbl.min.js",
    // name: "appInsights",
    // ld: 0,
    // useXhr: 1,
    crossOrigin: "anonymous",
    // onInit: null,
    // cr: 0,
    cfg: { // Application Insights Configuration
     connectionString: "YOUR_CONNECTION_STRING"
    }});
    </script>
    
  2. (可选)添加或更新可选的 JavaScript (Web) SDK 加载程序脚本配置,具体取决于是需要优化网页加载还是解决加载错误。

    Screenshot of the JavaScript (Web) SDK Loader Script. The parameters for configuring the JavaScript (Web) SDK Loader Script are highlighted.

JavaScript (Web) SDK 加载程序脚本配置

名称 类型 必需? 说明
src 字符串 必需 要从中加载 SDK 的完整 URL。 此值用于动态添加的 <script /> 标记的“src”属性。 你可以使用公共 CDN 位置,也可以使用自己的私有托管位置。
name 字符串 可选 已初始化的 SDK 的全局名称。 如果需要同时初始化两个不同的 SDK,请使用此设置。

默认值为 appInsights,因此 window.appInsights 是对已初始化实例的引用。

注意:如果你分配名称值,或者上一个实例已获分全局名称 appInsightsSDK,则 SDK 初始化代码会要求该名称以 window.appInsightsSDK=<name value> 的形式包含在全局命名空间中,以确保 JavaScript (Web) SDK 加载程序脚本框架正确无误,且代理方法得到初始化和更新。
ld 数值(毫秒) 可选 定义在尝试加载 SDK 之前要等待的加载延迟。 当由于 JavaScript (Web) SDK 加载程序脚本在错误时间加载而无法加载 HTML 页面时,请使用此设置。

默认值为超时后 0 毫秒。 如果使用负值,脚本标记会立即添加到页面的 <head> 区域,并阻止页面加载事件,直到脚本完成加载或失败。
useXhr boolean 可选 此设置仅用于报告 SDK 加载失败。 例如,当 JavaScript (Web) SDK 加载程序脚本阻止加载 HTML 页面,从而导致 fetch() 不可用时,此设置非常有用。

报告将先尝试使用 fetch()(如果可用),然后回退到 XHR。 将此设置设为 true 可绕过提取检查。 仅当在 fetch 无法发送失败事件 (例如 JavaScript (Web) SDK 加载程序脚本未成功加载) 的环境中使用应用程序时,才需要此设置。
crossOrigin 字符串 可选 通过包含此设置,为了下载 SDK 而添加的脚本标记将包含带有此字符串值的 crossOrigin 属性。 如果需要为 CORS 提供支持时,请使用此设置。 如果未定义(默认值),则不添加 crossOrigin 属性。 推荐的值为未定义(默认值)、"" 或“匿名”。 有关所有有效值,请参阅交叉源 HTML 属性文档。
onInit function(aiSdk) { ... } 可选 从 CDN 成功加载并初始化主 SDK 脚本后,将调用此回调函数(基于 src 值)。 当需要插入遥测初始值设定项时,此回调函数非常有用。 它将传递一个参数,该参数是对要为其调用的 SDK 实例的引用,并将在第一次初始页面浏览之前调用。 如果 SDK 已加载并初始化,则仍会调用此回调。 注意:在处理 sdk.queue 数组期间,将调用此回调。 请勿再向队列添加任何项,因为这些项会被忽略和删除。 (作为 JavaScript (Web) SDK 加载程序脚本版本 5 的一部分添加 -- 脚本中的 sv:"5" 值)。
cr boolean 可选 如果 SDK 无法加载,并且为 src 定义的终结点值为公共 CDN 位置,则此配置选项将尝试立即从以下备份 CDN 终结点之一加载 SDK:
  • js.monitor.azure.com
  • js.cdn.applicationinsights.io
  • js.cdn.monitor.azure.com
  • js0.cdn.applicationinsights.io
  • js0.cdn.monitor.azure.com
  • js2.cdn.applicationinsights.io
  • js2.cdn.monitor.azure.com
  • az416426.vo.msecnd.net
注意:az416426.vo.msecnd.net 部分受支持,因此不推荐使用。

如果 SDK 成功从备份 CDN 终结点加载,则它将从第一个可用终结点加载,这是在服务器成功执行加载检查时确定的终结点。 如果 SDK 无法从任何备份 CDN 终结点加载,则将显示 SDK 失败错误消息。

如果未定义,则默认值为 true。 如果不想从备份 CDN 终结点加载 SDK,请将此配置选项设置为 false

如果要从自己的专用托管 CDN 终结点加载 SDK,则此配置选项不适用。

将连接字符串粘贴到环境中

要在环境中粘贴连接字符串,请执行以下步骤:

  1. 导航到 Application Insights 资源的“概览”窗格。

  2. 找到“连接字符串”。

  3. 选择“复制到剪贴板”图标以将连接字符串复制到剪贴板。

    Screenshot that shows Application Insights overview and connection string.

  4. 将 JavaScript 代码中的占位符 "YOUR_CONNECTION_STRING" 替换为复制到剪贴板的连接字符串

    connectionString 格式必须遵循“InstrumentationKey=xxxx;....”。 如果提供的字符串不符合此格式,则 SDK 加载过程将失败。

    该连接字符串不被视为安全令牌或密钥。 有关详细信息,请参阅新的 Azure 区域是否需要使用连接字符串?

(可选)添加 SDK 配置

可选的 SDK 配置在初始化期间传递给 Application Insights JavaScript SDK。

若要添加 SDK 配置,请直接在 connectionString 下添加每个配置选项。 例如:

Screenshot of JavaScript code with SDK configuration options added and highlighted.

(可选)添加高级 SDK 配置

如果想使用插件为特定框架提供的其他功能,并选择启用“Click Analytics 插件”,请参阅:

确认有数据流

  1. 转到已为其启用 SDK 的 Application Insights 资源。

  2. 在左侧 Application Insights 资源菜单中的“调查”下,选择“事务搜索”窗格。

  3. 打开“事件类型”下拉菜单,然后选择“全部选择”以清除菜单中的复选框。

  4. 在“事件类型”下拉菜单中,选择:

    • Azure Monitor Application Insights 真实用户监视的页面视图
    • Click Analytics 自动收集插件的自定义事件

    数据可能在数分钟后才会显示在门户中。 如果显示的唯一数据是加载失败异常,请参阅排查 JavaScript Web 应用的 SDK 加载失败问题

    在某些情况下,如果不同版本的 Application Insights 的多个实例在同一页面上运行,则初始化过程中可能会出现错误。 对于这些情况和出现的错误消息,请参阅在一个会话中运行多个版本的 Application Insights JavaScript SDK。 如果遇到其中一个错误,请尝试使用 name 设置更改命名空间。 有关详细信息,请参阅 JavaScript (Web) SDK 加载程序脚本配置

    Screenshot of the Application Insights Transaction search pane in the Azure portal with the Page View option selected. The page views are highlighted.

  5. 如果要查询数据以确认数据是否流动:

    1. 在左侧面板中选择“日志”。

      选择“日志”时,将打开“查询”对话框,其中包含与你的数据相关的示例查询。

    2. 为要运行的示例查询选择“运行”。

    3. 如果需要,可以使用 KQL Kusto 查询语言 (KQL) 更新示例查询或编写新查询。

      有关基本 KQL 运算符,请参阅了解常见的 KQL 运算符

常见问题解答

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

什么是用户和会话计数?

  • JavaScript SDK 在 Web 客户端上设置了用于识别返回用户的用户 cookie,以及用于对活动进行分组的会话 cookie。
  • 如果没有客户端脚本,可以在服务器设置 cookie
  • 如果某个真实的用户在不同的浏览器中使用站点,或者使用私密/隐身浏览,或使用不同的计算机,则会进行多次计数。
  • 若要识别跨计算机和浏览器登录的用户,请添加对 setAuthenticatedUserContext() 的调用。

什么是 JavaScript SDK 性能/开销?

Application Insights JavaScript SDK 在网站上的开销最小。 该 SDK 经过压缩后只有 36 KB,只需大约 15 毫秒即可完成初始化,在网站中的加载时长可忽略不计。 使用该 SDK 时,系统会快速加载库的极少组件,并在后台下载完整脚本。

此外,从 CDN 下载脚本时,对页面的所有跟踪都会排队,因此在页面的整个生命周期内都不会丢失任何遥测数据。 此设置过程可为页面提供一个无缝分析系统,而用户察觉不到该系统。

JavaScript SDK 支持哪些浏览器?

Chrome Firefox IE Opera Safari
Chrome 最新版 ✔ Firefox 最新版 ✔ v3.x:IE 9+ & Microsoft Edge ✔
v2.x:IE 8+ 兼容和 Microsoft Edge ✔
Opera 最新版 ✔ Safari 最新版 ✔

在哪里可以找到 JavaScript SDK 的代码示例?

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

ES3/Internet Explorer 8 与 JavaScript SDK 的兼容性如何?

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

这样说并不意味着我们仅支持最少量的常用功能集。 我们需要保持 ES3 代码的兼容性。 新功能需要以不会中断 ES3 JavaScript 分析的方式添加,且需作为可选功。

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

JavaScript SDK 是否为开放源代码?

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

支持

后续步骤