logline：轻量、实用和客户端级的前端日志记录工具
SusanneTier
7年前
<h2>Logline</h2> <p>logline是一个轻量，实用和客户端级的前端日志记录工具。</p> <h2>为何前端定位问题很困难</h2> <p>前端同学对此肯定深有体会，代码发出去之后，犹如脱缰的野马，运行在万千的客户终端上，等到产品和后台反馈问题到我们这边，很多时候定位问题只能靠猜，尤其是一些偶发诱因，因为根本不知道用户是如何操作的，真实环境遇到的问题通常是很多随机因素叠加的形成的，因此很难回放用户的操作来还原现场找到原因。这个时候，我们想，如果有一个像后台一样详实的可分类和检索的运行日志，无疑将会提供巨大的帮助。</p> <h2>应用场景</h2> <ul> <li> <p>回放用户细节操作</p> <p>真实应用场景下，用户的行为可能是不可预料的，甚至用户自己也无法记得自己的操作，有了日志，我们有了回放用户操作和代码运行状态的能力。</p> </li> <li> <p>核心流程监控</p> <p>在产品的一些核心流程中，我们可以在用户出错的情况下主动上传用户日志，以便我们可以快速统计和定位用户遇到的问题。</p> </li> <li> <p>主动抓取用户的日志分析用户行为</p> <p>有时候在用户不配合开发人员的时候，我们可以设计一种策略，比如我们在线上发布一个json文件，里面配置一个希望主动抓取日志的用户列表，当我们的产品在用户手机上被打开后，延时下载（避免影响主流程性能）这个json，当匹配当前用户时，直接主动上报该用户的日志。</p> </li> <li> <p>统计和辅助分析JS错误</p> <p>我们可以记录js的报错，包含调用队列一起记录，直接上传此错误日志或者在累计达到一个阈值的时候统一上传。</p> </li> </ul> <h2>特性</h2> <ul> <li>无外部依赖</li> <li>日志记录</li> <li>客户端级</li> <li>websql/localstorage/indexeddb三种日志协议</li> <li>命名空间</li> <li>日志等级</li> <li>日志清理（防止日志过多，占用上传带宽和占满用户允许的内存）</li> </ul> <h2>快速上手</h2> <h3>1. 安装</h3> <p>通过bower</p> <pre> <code class="language-javascript">bower install logline</code></pre> <p>直接下载</p> <p>访问 <a href="/misc/goto?guid=4959728698537280057" rel="nofollow,noindex">https://github.com/latel/logline/releases</a> ，选择需要的版本下载，引入自己的项目。</p> <h3>2. 引入脚本</h3> <p>Logline 支持直接使用 script 标签引用，也支持 AMD 模块加载器.</p> <pre> <code class="language-javascript">// Script标签引入方式 <script src="./mod/logline.min.js"></script> <script> // 使用indexedDB协议 Logline.using(Logline.PROTOCOL.INDEXEDDB); </script> // AMD模块方式 var Logline = require('./mod/logline.min');</code></pre> <h3>3. 选择日志协议</h3> <p>目前一共支持三个协议， 三个协议都被直接挂载在Logline对象上以便一些特殊的应用场景，也更好的符合语义化:</p> <ul> <li>websql: Logline.PROTOCOL.WEBSQL</li> <li>indexeddb: Logline.PROTOCOL.INDEXEDDB</li> <li>localstorage: Logline.PROTOCOL.LOCALSTORAGE</li> </ul> <p>你可以在引入Logline之后，使用 using 主动选定一个期望使用的日志协议。</p> <pre> <code class="language-javascript">Logline.using(Logline.PROTOCOL.WEBSQL);</code></pre> <p>如果你没有提前选择一个日志协议，那么当你调用Logline的相关 API 时，Logline 会根据你在构建时给定的参数作为优先级来选择可用的优先级最高的协议。 比如你的自定义构建命令是 npm run configure -- --with-indexeddb --with-websql --with-localstorage ， 如果 indexeddb 协议可用，那么indexeddb将作为自动选择的协议。 如果 indexeddb 协议不可用但是 websql 协议可用，那么将选择 websql 协议，如此类推。 如果最后发现所有的协议都不可用，将会抛出错误。</p> <h3>4. 记录日志</h3> <pre> <code class="language-javascript">// 不同的模块使用不同的日志会话 var spaLog = new Logline('spa'), sdkLog = new Logline('sdk'); // 不包含数据的，描述为 init.succeed 的记录 spaLog.info('init.succeed'); // 包含错误描述数据，描述为 init.failed 的记录 spaLog.error('init.failed', { retcode: 'EINIT', retmsg: 'invalid signature' }); // 不包含数据的，描述为 outdated 的记录 sdkLog.warning('outdated'); // 包含错误描述数据，描述为 system.vanish 的记录 sdkLog.critical('system.vanish', { // debug infos here });</code></pre> <h3>5. 读取日志</h3> <pre> <code class="language-javascript">Logline.getAll(function(logs) { // process logs here });</code></pre> <h3>6. 清理日志</h3> <pre> <code class="language-javascript">Logline.keep(.5); // 保留半天以内的日志，如果不传参则清空日志 Logline.clean(); // 清空日志并删除数据库</code></pre> <h3>7. 自定义数据库名</h3> <p>由于 indexeddb, websql 和 localStorage 都是同域共享的，这时候 Logline 默认的数据库名 logline 可能会已经被占用，需要指定一个新的数据库名。 可以通过下面2个方法指定数据库名。</p> <pre> <code class="language-javascript">// 调用`using`时，同时指定第二个参数作为数据库名 Logline.using(Logline.PROTOCOL.WEBSQL, 'newlogline'); // 调用`database`来指定数据库名 Logline.database('newlogline');</code></pre> <h2>自定义构建</h2> <p>目前Logline一共实现了 localstorage 、 websql 和 indexeddb 三个日志协议，默认是全部打包，可能你只想使用其中某个协议而已，你可以通过 npm run configure 来自定义构建你需要的版本。这样有利于减小包的大小。</p> <pre> <code class="language-javascript">// 不跟参数默认构建所有协议 npm run configure // 配置你需要的协议，去掉不需要的协议申明--with-xxx npm run configure -- --with-localstorage --with-websql --with-indexeddb // 重新打包 npm run build // 去dist目录寻找新构建的打包文件</code></pre> <h2>FAQ</h2> <h3>如何上传日志？</h3> <p>从v1.0.1以开始，日志上传功能被移除，我们希望logline更专注于日志的记录和维护工作，你可以通过 Logline.getAll 来获取日志来自行实现上传过程。</p> <h3>如何分析日志</h3> <p>由于Logline上传的日志格式符合标准，具有良好的可阅读性，因此我们可以在某种程度上直接使用命令行工具或者编辑器来阅读。 但是对命令行不熟悉的用户使用可能仍然有困难，因此有必要使用Web技术栈搭建一个易于使用并且视觉良好的工具。</p> <p>我们为此准备了Logline-viewer以供使用。</p> <p> </p>