2022基调听云Web-V3.6.5.0-使用手册-客密

DOCPROPERTYTrademark&ProductType产品商品名称DOCPROPERTYManualName使用说明书4产品业务功能DOCPROPERTYTrademark&ProductType产品商品名称DOCPROPERTYManualName使用说明书基调听云Web使用手册版本V1.00STYLEREF封面-产品信息基调听云WebSTYLEREF封面-手册名称使用手册STYLEREF标题1-无序目录SourceMap。LCP说明LargestContentfulPaint(LCP)用于衡量标准报告视口内可见的最大内容元素的渲染时间。为了提供良好的用户体验，网站应努力在开始加载页面的前2.5秒内进行最大内容渲染。因此，LCP指标就非常有价值了，因为这个值是根据页面加载渲染不断变化的，如果页面有一个loading动画，然后才渲染出具体内容，那么这个指标计算出来的就是具体内容的加载速度，而非loading动画的加载速度。LCP考虑哪些元素LCP目前并不会计算所有元素，因为这样会使这个指标变得非常复杂，它现在只关注下面的元素：<img>元素<image>元素内的<svg>元素<video>元素通过url()函数加载背景图片的元素。包含文本节点或其他内联文本元素子级的块级元素。说明：为了在开始时保持简单，将元素限制到这个有限的集合是有意的。随着研究的深入，将来可能会添加更多的元素。如何计算LCP页面上最大的元素即绘制面积最大的元素，所谓绘制面积可以理解为每个元素在屏幕上的“占地面积”，如果元素延伸到屏幕外，或者元素被裁切了一部分，被裁切的部分不算入在内，只有真正显示在屏幕里的才算数。图片元素的面积计算方式稍微有点不同，因为可以通过CSS将图片扩大或缩小显示，也就是说，图片有两个面积：“渲染面积”与“真实面积”。在LCP的计算中，图片的绘制面积将获取较小的数值。例如：当“渲染面积”小于“真实面积”时，“绘制面积”为“渲染面积”，反之亦然。页面在加载过程中，是线性的，元素是一个一个渲染到屏幕上的，而不是一瞬间全渲染到屏幕上，所以“渲染面积”最大的元素随时在发生变化。如果元素被删除，LCP算法将不再考虑该元素，如果被删除的元素刚好是“绘制面积”最大的元素，则使用新的“绘制面积”最大的元素创建一个新的性能条目。该过程将持续到用户第一次滚动页面或第一次用户输入（鼠标单击，键盘按键等），也就是说，一旦用户与页面开始产生交互，则停止报告新的性能指标。在以上时间轴中，最大的元素随内容加载而变化。在第一个示例中，新内容被添加到DOM中，并且更改了最大的元素。在第二个示例中，布局发生更改，以前最大的内容从视口中删除。通常情况下，延迟加载的内容要大于页面上已存在的内容。改善LCPLCP较差的最常见原因是：服务器响应时间慢阻断渲染的Javascript和CSS资源加载时间慢客户端渲染所以我们从上面的角度去考虑改善LCP。优化服务器浏览器从服务器接收内容所需的时间越长，则在屏幕上呈现任何内容所花费的时间就越长。更快的服务器响应时间可以直接改善包括LCP在内的所有页面加载指标。衡量服务器相应时间有一个专门的指标：首字节相应时间（TTFB）是最初的网络请求被发起到从服务器接收到第一个字节这段时间，它包含了TCP连接时间，发送HTTP请求时间和获得响应消息第一个字节的时间。你可以尝试在下面几个方便优化TTFB：缓存HTML离线页面，缓存页面资源，减少浏览器对资源的请求。尽量减小资源阻断渲染：CSS和JavaScript压缩、合并、级联、内联等等。对图片进行优化。转化图片的格式为JPG或者WEBP等等的格式，降低图片的大小，以加快请求的速度。对HTML重写、压缩空格、去除注释等。减少HTML大小，加快速度。使用preconnect尽快与服务器建立链接、使用dns-prefetch尽快进行DNS查找。使用CDN加快请求速度。优化阻断渲染的资源JavaScript和CSS都是会阻断页面渲染的资源，需要尽可能的对CSS和JavaScript文件进行压缩、延迟加载首屏无需使用的JavaScript、内联关键的CSS等来减小阻断时间。优化资源加载时间刚才我们上面提到的这些资源，如果在首屏进行渲染，则加载这些元素所花费的时间将直接影响LCP。<img>元素<image>元素内的<svg>元素<video>元素通过url()函数加载背景图片的元素。包含文本节点或其他内联文本元素子级的块级元素。你可以使用下面的手段进行优化：对图片进行优化。转化图片的格式为JPG或者WEBP等等的格式，降低图片的大小。对重要的资源进行预加载，比如为style标签添加rel="preload"属性。使用Gzip和Brotli压缩页面资源，降低传输时间。使用serviceworker缓存资源。服务端渲染使用服务端渲染可以确保首先在服务器上呈现页面内容，可以有效改善LCP，但是相比客户端渲染的缺点是会加大页面从而影响TTFB、服务端渲染需要等待所有JS执行完毕后才能相应用户输入，这会使交互体验变差。首屏算法更新JS探针3.2.2版本将首屏的算法改为取LCP的耗时，因为LCP更符合业务和用户体验对首屏的要求。原首屏算法为计算首屏内全部的元素加载完成，若还想使用该算法可在探针中关闭LCP。3.2.2及以上版本探针默认尝试使用LCP（largestcontentfulpaint）计算首屏。如何禁用LCP首屏计算通过探针配置lcp_enable=false关闭lcp算法计算首屏。{...,lcp_enable:false...}如何提前停止LCPPerformanceObserver每次有更大的区域被渲染，LCP可能在页面加载过程中多次触发。探针支持在某个时间点停止继续监控LCP触发，并记录此时间点，如果在此之前没有获取到LCP触发或LCP算法被禁用，那么使用停止的时间点作为首屏时间。if(window.TINGYUN&&window.TINGYUN.stopLCPObserver){window.TINGYUN.stopLCPObserver();}SPA首屏和完全加载指标说明背景现代Web开放框架大多数使用MVVM框架，例如Angular、Vue、React、Flutter等，该类型框架通常在DOM加载完成DomContentLoaded事件触发之后，执行框架的初始化、路由的加载，API接口的调用在数据加载完毕之后再进行。首屏LCP的监控LCPPerformanceObserver（最大元素渲染监听器）该监听器在UI发生变动后会不断触发，所以我们只要找到一个合适的停止点则就能够找到用户直观感受的页面完成时间（首屏），例如在页面加载完毕客户的UI或子路由跳转展示完毕之后获取最新的LCP值，则和用户的直观感受更为接近。总耗时监控页面总耗时，不以navigationTiming的loadEventEnd为结束点。标记loadEventEnd事件触发之前的xhr请求并记录，可配置请求黑名单和请求白名单进行过滤。监控DOM变更事件，每次触发DOM变更事件时，判断触发时间的前resource_associate_threshold配置时间(默认为100ms)内是否存在已发起未结束或已结束的XHR请求，若有则查找DOM变更内的IMG/SCRIPT/IFRAME事件并追加onload监听，在页面加载完毕时间，发送页面性能数据。配置参数SPA监控方式开关，默认打开：spa_metric_enable。示例：{...,"spa_metric_enable":true...}浏览器load事件触发时计算延迟时间：pfDelay。延迟时间取没有mark指标中的最大值，如果都mark了，则延迟时间为0；没有pfDelay，则延迟时间为0。关于mark指标自定义打点，请参见《基调听云WebJS探针接口说明》中的指标自定义打点小节。示例：pfDelay:{le:1000,dr:2000,fs:1000,fp:1000}页面加载完成默认等待时间，默认500ms：page_load_delay。示例：{...,"page_load_delay":1000...}过滤页面加载事件加入的请求和资源过滤配置白名单：event_resources。示例：{...,"event_resources":["name01","name02"]...}过滤页面加载事件加入的请求和资源过滤配置黑名单：event_resources_ignore。示例：{...,"event_resources_ignore":["name01","name02"]...}元素加载最长等待时间，默认10S：resource_wait_time。示例：{...,"resource_wait_time":10000...}元素和Ajax请求阈值，默认为100ms：resource_associate_threshold。示例：{...,"resource_associate_threshold":500...}SourceMap对于前端应用来说，JS错误的发生直接影响前端应用的质量，因此对于JS错误的定位及诊断显得尤为重要。基调听云提供了SourceMap上传来还原代码真正的错误位置，还原JS错误现场。这样使得开发者能够迅速定位出错的源代码位置以及相应的代码块。什么是SourceMapSourceMap是一个存储源代码与编译代码对应位置映射的信息文件，便于开发人员定位上述代码错误。实际上，它就是一个JSON键值对，利用VLQ编码与特定的规则存储位置信息。简而言之，可以理解为SourceMap在处理前的代码和处理后的代码之间搭建了一座桥梁。SourceMap上传支持两种方式：CLI和Webpack插件。CLI使用说明TingyunCLI是一个CLI程序，是上传SourceMap的主要方式。安装npm安装当前工作目录安装：进入前端工程目录，安装CLI包。npminstall@tingyun-common/cli验证安装成功。./node_modules/.bin/tingyun-cli-v如果终端中打印tingyun-cli版本证明安装成功。全局安装：安装。npminstall-g@tingyun-common/cli--unsafe-perm需要确保有权限访问全局的node_modules目录，如果在Linux、Mac环境遇到权限问题，建议使用root安装。sudonpminstall-g@tingyun-common/cli--unsafe-perm验证安装成功。tingyun-cli-v如果终端中打印tingyun-cli版本证明安装成功。其他npm安装配置CLI下载地址：--tingyuncli_cdnurl=<下载地址根路径>使用示例：npminstall@tingyun-common/cli--tingyuncli_cdnurl=/path手动下载可执行文件可以在\h基调听云文件下载服务器查看tingyun-cli已经发布的版本，并下载到Linux、Mac、Windows平台的可执行文件。下载之后可以重命名为tingyun-cli.exe或tingyun-cli来使用。注意可执行文件是CLI程序，需要在终端中使用。使用初始化。TingyunCLI依赖于配置文件来使用，配置文件名为.tingyunclirc或.tingyunclirc.toml，格式为toml格式。配置文件信息可以在应用设置中复制或者通过运行tingyun-cliinit提供的交互式信息输入工具来初始化。在使用CLI上传SourceMap之前，需要保证当前目录或用户目录存在配置文件。在项目工作目录中执行初始化命令生成配置文件.tingyunclirc.toml。tingyun-cliinit-y打开配置文件。配置文件使用toml格式，生成的配置文件说明：[auth]#平台accesstoken,应用设置获取token=""[base]#应用名称,可选,标记作用,应用设置获取app_name=""#应用token,应用设置获取app_token=""#sourcemap上传地址,应用设置获取beacon=""#产品类型,应用设置获取product_type="web"在应用设置>SourceMap页面复制配置信息，粘贴到.tingyunclirc.toml文件，保存。上传SourceMap。命令结构：tingyun-clireleaseupload<版本><上传文件或目录>--sourcemap为了准确解析不同版本JS文件的报错，SourceMap文件必须上传到某个版本下(关于版本CLI命令见下方完整命令列表)。此版本是用户项目的应用版本，每次JS文件重新打包都需要重新更换版本上传。示例：tingyun-clireleaseuploadV1.0.0./dist--sourcemap上传dist目录下的SourceMap文件到V1.0.0版本。设置应用版本。为了准确关联JS错误版本，用户项目中需要在页面全局设置变量TINGYUN_RELEASE，变量类型为对象，属性id标识版本名称。此值需要在每次发版时与上一步指定的版本保持一致。window.TINGYUN_RELEASE={id:'V1.0.0'}探针会获取TINGYUN_RELEASE的id作为应用版本上传。CLI命令查看版本：tingyun-cli-v交互式问卷模式在当前目录初始化配置文件：tingyun-cliinit--yes，-y可以跳过问卷，生成一个模板配置文件： tingyun-cliinit-y展示当前版本列表tingyun-clireleaselist删除版本tingyun-clireleasedelete<release>创建版本tingyun-clireleasenew<release>上传版本tingyun-clireleaseupload<release><files>...[flags]Flags说明：--sourcemap：按SourceMap形式处理上传文件，默认识别.map文件，并尝试解析.js中sourcemapping映射。--no-overwirte：上传不覆盖同名文件，默认覆盖。--config：指定配置文件路径，全局flags，对所有命令子命令都生效。示例： tingyun-clireleaseuploadV1.0.0./dist--sourcemap--config/my/config/dir/.tingyunclircWebpack插件使用说明Webpack插件简化了CLI上传SourceMap流程，可以更好的集成到项目的版本发布中。使用安装。进入前端项目的根目录，通过npm安装：npminstall@tingyun-common/source-map-webpack-plugin--save-dev在Webpack配置中加入SourceMap插件。//导入sourcemap插件constTingyunSourceMapWebpackPlugin=require('@tingyun-common/source-map-webpack-plugin');module.exports={//建议只在生产模式使用mode:'production',//...plugins:[newTingyunSourceMapWebpackPlugin({//指定打包生成的文件目录,根据实际情况填写,例如:'./dist'include:'<上传目录或文件>',//设置上传sourcemap的版本号,如果不设置,插件会自动生成,例如;V1.0.0release:'<版本号>'//指定上传的配置信息。如果当前项目目录存在tingyun-cli配置文件.tingyunclirc或.tingyunclirc.toml可以不写beacon:'<上传地址>',appToken:'<app_token>',token:'<access_token>',productType:'<产品类型>',//web或mp}),//...//其他插件],};Webpack插件在每次执行时都会创建版本并上传SourceMap，建议只在生产环境打包时执行插件，防止大量不必要的版本上传。可参考Webpack官方文档：\h生产打包的最佳实践。如果当前目录存在tingyun-cli配置文件.tingyunclirc或.tingyunclirc.toml，Webpack插件配置中可以不设置上传信息。Demo项目请参见项目地址。配置示例下面列举了流行的脚手架项目的使用方式。根本目的是在Webpack配置中加入基调听云SourceMap插件，如果下列参考配置没有覆盖你的使用场景，请根据实际情况配置。使用前首先确保已经安装Webpack插件：npminstall@tingyun-common/source-map-webpack-plugin--save-dev然后参考下列配置操作。create-react-app建议使用react-app-rewired来增加Webpack插件。如果你的项目中已经使用eject脚本暴露了Webpack配置，请自行分析项目配置添加Webpack插件。示例使用的版本：create-react-app4.0.3安装react-app-rewired。npminstallreact-app-rewired--save-dev修改package.json脚本的script部分，使用react-app-rewired替换react-scripts。"scripts":{"start":"react-app-rewiredstart","build":"react-app-rewiredbuild","test":"react-app-rewiredtest","eject":"react-scriptseject"},在项目根目录添加或修改config-overrides.js。constTingyunSourceMapWebpackPlugin=require('@tingyun-common/source-map-webpack-plugin');module.exports={webpack:(config)=>{if(process.env.NODE_ENV==="production"){if(!config.plugins){config.plugins=[];}//生产环境加入webpack插件config.plugins.push(newTingyunSourceMapWebpackPlugin({include:"./build",//其他配置}))}returnconfig;},}打包。npmrunbuild执行打包命令后，控制台会打印插件输出的上传信息。vue-cli示例使用的版本：@vue/cli4.5.13创建或修改vue.config.js文件。constTingyunSourceMapWebpackPlugin=require('@tingyun-common/source-map-webpack-plugin');module.exports={configureWebpack:(config)=>{if(process.env.NODE_ENV==="production"){//生产环境加入webpack插件config.plugins.push(newTingyunSourceMapWebpackPlugin({include:"./dist",//其他配置}))}},};打包。打包命令请根据实际情况填写，默认是build。npmrunbuild执行打包命令后，控制台会打印插件输出的上传信息。angular-cli示例使用的版本：AngularCLI:12.0.4进入项目目录安装@angular-builders/custom-webpack。npminstall@angular-builders/custom-webpack--save-dev修改angular.json。"projects":{...//[project]是实际项目名"[project]":{..."architect":{...//修改对应的ng命令,此处以修改build为例"build":{//修改默认builder//"builder":"@angular-devkit/build-angular:browser","builder":"@angular-builders/custom-webpack:browser""options":{//增加自定义webpack文件配置"customWebpackConfig":{//webpack配置文件名称,名称自定义"path":"./webpack.config.js"}},"configurations":{"production":{//如果没有开启sourcemap生成,设置开启sourcemap"sourceMap":true}}修改/创建Webpack配置文件。此处配置文件的生成位置取决于angular.json中配置的路径。webpack.config.jsconstTingyunSourceMapWebpackPlugin=require('@tingyun-common/source-map-webpack-plugin');module.exports=(config,options)=>{if(config.mode==="production"){if(!config.plugins){config.plugins=[];}config.plugins.push(newTingyunSourceMapWebpackPlugin({include:"./dist",//上传配置可以在此处指定或者创建cli配置文件}))}returnconfig;};打包。npmrunbuild执行打包命令后，控制台会打印插件输出的上传信息。Web探针报表配置//描述对外提供的配置项exporttypeReportConfigOptions={//环境默认:无env?:string//应用版本默认:无release?:string//公共配置common?:{//探针debug开关默认:falsedebug?:boolean//session模式默认:autosessionMode?:'auto'|'manual'//强制指定发送的数据协议默认:无sendProtocol?:string}//页面监控配置page?:{//监控路由加载默认:truerouterEnabled?:boolean//指定监控的路由模式默认:autorouterMode?:'history'|'hash'|'auto'//路由加载操作默认等待时间,单位ms默认:500routerOperationDelay?:number//上传没有ajax的hash路由切换,默认:falseuploadNoAjaxHashRouter?:boolean;//加载过程中无ajax默认等待时间,单位ms默认:500pageLoadDelay?:number//是否使用lcp作为首屏默认:truelcpAsFs?:boolean;//是否开启mutationObserver监控默认:truemutationEnabled?:boolean;//不使用lcp计算首屏时,设置首屏线上的图片资源默认:无fsResources?:string[];}//ajax监控配置ajax?:{//ajax监控总开关默认:trueenabled?:boolean//ajaxxhr监控开关默认:truexhrEnabled?:boolean//ajaxfetch监控开关默认:truefetchEnabled?:boolean//mPaas监控开关默认:truemPaaSEnabled?:boolean//监控xhr的setRequestHeader接口默认:truehookXhrSetRequestHeader?:boolean//Ajax黑名单默认:无ignoreUrls?:string[]}//JS错误监控配置jsError?:{//是否监控JS错误默认:trueenabled?:boolean,//是否上报空文件名的js错误默认:falseuploadEmptyFileErrors?:boolean//是否对异步回调函数进行trycatch默认:falsecatchAsyncCallback?:boolean}//操作数据operation?:{//用户操作自动监控开关默认:trueenabled?:boolean//是否监控html标签上onclick,onsubmit属性绑定的回调默认:trueinlineEventEnabled?:boolean//是否hookHTMLEtotype中的onXXX(onclick,onsubmit)属性默认:trueonPropertyEnabled?:boolean//是否hookaddEventListener/removeEventListener默认:trueeventListenerEnabled?:boolean//inlineevent关联下级请求的阈值单位ms默认200inlineEventThreshold?:number//是否开启自动跨页面事件默认:truecrossPageEnabled?:boolean//操作下Ajaxiframe等元素的白名单默认:无itemUrls?:string[]//操作下Ajaxiframe等元素的黑名单默认:无ignoreItemUrls?:string[]//操作超时时间单位ms默认60000timeout?:number;//操作下元素挂载到ajax回调后的时间差阈值,单位ms,默认:100resourceAssociationThreshold?:number;//操作下挂载到ajax的元素加载的最长等待时间,单位ms,默认10000resourceAssociationWaitTime?:number;}//apm配置requestTracing?:{//是否主动添加apm请求头默认fals