Bragi-Node, Bragi是彩色的,离散的,复杂的NodeJS日志框架

分享于 

17分钟阅读

GitHub

  繁體 雙語
Bragi is colorful, discrete, and sophisticated NodeJS logging framework
  • 源代码名称:Bragi-Node
  • 源代码网址:http://www.github.com/erikhazzard/Bragi-Node
  • Bragi-Node源代码文档
  • Bragi-Node源代码下载
  • Git URL:
    git://www.github.com/erikhazzard/Bragi-Node.git
    Git Clone代码到本地:
    git clone http://www.github.com/erikhazzard/Bragi-Node
    Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/erikhazzard/Bragi-Node
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
    
    Bragi: Javascript记录器- NodeJS

    NPM version

    Bragi

    注意:这是一个早期版本,并且API可能会改变。 欢迎使用改进和请求请求。 查看描述这个库及其一些特性的文章,它的特点是。

    Bragi是具有颜色,自定义日志级别和服务器报告功能的javascript日志库。 Bragi允许你编写可以在代码中留下的日志消息,并允许你指定输出到控制台的日志。

    这里存储库用于NodeJS版本的Bragi。 你还可以查看浏览器的版本。

    Bragi

    Bragi是Poetry的Norse。

    安装和使用

    $ npm install bragi

    然后,将它的包含在代码中:

    var logger =require('bragi');

    接下来,记录一些内容:

    logger.log('groupname', 'Hello world');

    默认情况下启用所有日志组。 对 log的调用采用两个必需参数: groupNamemessage 日志消息中还包含任何附加参数( 如对象信息)。 举个例子:

    logger.log('groupname', 'Here is some user info', { name:'Ironman', weaknesses:null });

    Bragi提供的好处之一是能够为组( 用冒号隔开) 提供任意组名称和命名空间。 举个例子:

    logger.log('userController:fetchInfo', 'fetching user information...');

    由于groupname是一个字符串,因此可以动态创建它:

    logger.log('userController:fetchInfo:ironman', 'fetching user information...');

    使用组名,我们可以通过组和它们的命名空间过滤消息,或者通过正则表达式( 比如,我们可以显示 ironman 用户的所有日志)。 默认情况下,将记录所有组。

    日志组( 日志级别)

    日志级别是线性的其他库不同,在Bragi日志级别是离散和任意的。 你可以拥有嵌套日志级别 比如: logger.log("group1:subgroup1","Log message %O", {key: 42});

    通过任意的日志级别,可以对输出的日志消息进行精细的粒度控制。

    指定要记录的内容

    groupsEnabled: {String}s 或者 {RegExp} 正规表达式的{Array},指定可以记录哪些组。 注:也可以是 {Boolean}: 如果为 true,则记录所有日志记录;如果为 false,则不会记录任何内容。 执行白名单。

    groupsDisabled: {String}s {RegExp} 正规表达式的{Array},指定从日志记录中排除哪些组。 如果你想记录所有的东西,这是很有用的,除了一些特殊的群组。 作为黑名单。

    可以直接访问这些数组,也可以使用 logger.addGroup("groupName" ); ( 或者 logger.addGroup(/groupRegex/); ) 添加组,或者使用 logger.removeGroup("groupName" ); ( 或者 logger.addGroup(/groupRegex/); ) 从 groupsEnabled array 中删除一个组。

    注意,对 addGroup的第一个调用将改变日志记录的行为所有只记录提供的组 provided。

    addGroupremoveGroup 函数返回记录器对象,因此可以将它们链接在一起: logger.addGroup("group").addGroup("otherGroup");

    示例:

    var logger =require('bragi');

    现在,让我们启用所有包含用户ironman的group1:subgroup1 日志和日志消息,用 :ironman 表示:

    logger.options.groupsEnabled= [ 'group1:subgroup1', '.*:ironman' ]

    这将记录所有 group1:subgroup1 日志,包括嵌套的子组: 例如 group1:subgroup1:subsubgroup1

    如果你可以根据某些变量动态地构建日志( 你甚至可以动态地构建它),那么 .*:ironman 会。

    若要指定黑名单,请使用 groupsDisabled。 这将记录除 group1 之外的所有内容:

    logger.options.groupsEnabled=true; logger.options.groupsDisabled= ['group1'];

    内置日志类型

    目前只存在两个内置日志类型: errorwarn 这些类型也可以是命名空间化的( 比如,error:group1:subgroup1 是有效的)。 对于错误消息,background 始终为红色,前景为白色。 对于警告消息,background 为 yellow,前景为白色。 文本也将为 blink。 这些是保留的颜色,所以只要存在红色 background 和白色文本,就可以立即知道错误已经被记录。

    注意,errorswarn 日志将始终包含,除非在 groupsDisabled 中设置 explictly。

    示例

    Log exampleexamples 文件夹中,有各种调用和配置Bragi的示例。

    Util

    Bragi提供了一对实用函数来帮助你编写具有强视觉线索的日志消息。

    • 所有的符号都可以在 lib/bragi/symbols.js 中查看

    • logger.util.print( message, color ) :这里函数接收消息 {String} 和颜色 {String},并返回传递的颜色中的消息字符串。

    配置

    Bragi配置

    Bragi有两个配置级别- Bragi宽配置和传输级配置。

    配置 bragi,然后要求它设置 options 对象中定义的属性。 举个例子:

    var logger =require('bragi');logger.options.PROPERTY=VALUE;

    可用选项包括:

    • groupsEnabled: {Strings} 或者 {RegExp} ( 正规表达式 )的array,指定要记录哪些组- 将向所有可用传输发送哪些消息
    • groupsDisabled: {Strings} 或者 {RegExp} ( 正规表达式 )的array,指定从日志中排除哪些组。 这里操作将执行黑名单,并优先于 groupsEnabled 中定义的日志。
    • storeStackTrace: false 默认情况下,如果设置为 true,将存储堆栈跟踪。 这提供了更多信息,但增加了开销。 在开发过程中非常有用,在生产中应该考虑权衡
    • hideUnformattedParameters: false 默认情况下,如果将它的设置为 true,则不在消息字符串中包含附加参数。 如果设置为 false,则所有附加对象都将嵌入到消息字符串中。 比如在默认情况下 logger.log('group', 'message', {a:1}) 将导致字符串 "group:message {a:1}"。 其他对象始终包含在日志数据对象中并可以在传输中访问,但是你可能并不总是希望在生成的消息字符串中显示其他对象。 如果这里选项设置为 true,则必须包括格式化程序( 比如 ,"%j") inside,以便在字符串中显示它的他对象。 例如: logger.log('group', 'message: %j', {key: 'val'}) 将生成消息字符串 "group:message: {key:'val'}"。 如果不包含 %j 或者其他格式化程序,则不会将其他对象嵌入到字符串中。 这是位置,所以你可以做一些事情 logger.log('group', 'only include first two: %j %j', {a:1}, {b:1}, {c:1}); 在这个例子中,前两个对象( {a:1}{b:1} ) 将包含在消息字符串中,但是 {c:1} 不会存储在日志数据中
    输出- 传输

    默认情况下,Bragi使用控制台传输,它将彩色消息记录到控制台。

    更改传输

    当前,你可以使用 logger.transports.empty(); 删除所有传输。

    若要添加传输,请使用 logger.transports.add( new logger.transportClasses.Transport( {} ) ) ( 传输是传输,在 lib/bragi/transports/ 中找到)。

    当前可用的传输有 ConsoleConsoleJSONHistoryFile。 未来传输包括将数据发送到远程主机( 比如,Graylog )。

    有关删除默认传输和添加新传输的示例,请参见 examples/example-json.js

    配置传输

    所有传输以最少的groupsEnabledgroupsDisabled 进行。 这允许传输级别配置使用哪些日志消息。 默认情况下,它们将使用全局记录器对象上设置的任何。 比如,如果你想把所有的日志发送到远程主机,但是只想在控制台输出中显示错误日志,那么这是很有用的。

    若要配置已经添加到记录器中的传输,可以使用 logger.transports.get("TransportName"); 注意,这将返回传输( 这是因为你可能有相同类型的多个传输- 比如,有可能有多个文件传输)的一个 {Array}。

    注意:控制台传输支持批处理,批处理将日志记录到控制台。 这可能是一个小的性能优化;特别是,如果你将输出输出到文件,这将大大减少。 有关用法的示例,请参阅 example-simple.js。 例如要启用:

    
    logger.transports.get('Console').property({ 
    
    
     showStackTrace: false, showMeta: true,
    
    
     batchEnabled: true
    
    
    });
    
    
    
    

    设置属性

    要设置属性,你可以:

    • 单独访问传输对象( 比如。 logger.transports.get('console')[0].PROPERTY= VALUE )
    • 通过调用为所有返回的传输设置选项 .property( key, value )

    例如要在控制台输出中显示堆栈跟踪,请执行以下操作: logger.transports.get('console').property('showStackTrace', true);

    如果只传入一个键,则它充当 getter ( 并返回值的array )。 如果传入键和值,它将为每个返回的数据设置属性。 注意:如果你在文件传输上使用了这个,并且更改输出路径,所有文件传输都将记录到该文件。

    请参阅 examples/example-simple.json ( 或者 test/test.js ) 示例用法。

    格式- 消息

    如果不使用 %j 或者 %s 或者 %s 格式字符串调用 bragi,则任何其他参数都将不会被记录。 但是,它们将被添加到内部数据对象,并且可以被传输器使用。 例如如果你要将大量数据传递给 Graylog,这很有用,但是不希望在控制台日志本身中显示。 例如:

    
     logger.log("group1","Hello there", {note:"this won't be logged"});
    
    
    
    

    若要显示日志消息中的数据,只需传入'%j':

    
     logger.log("group1","Hello there %j", {note:"this WILL be logged"});
    
    
    
    

    控制台传输- 配置

    showMeta: 默认情况下为 {Boolean} true。 指定是否将元信息( 呼叫人,时间,等等 ) 显示为每个消息 showStackTrace 之后的新行: 默认情况下,{Boolean} false 设置为 true。如果设置为,则将记录器的storeStackTrace 设置为 {true}. 将打印每个日志的堆栈跟踪

    编写自定义传输

    所有传输都必须是 containg Prototype原型 name 属性和 log 函数的函数。 传输函数本身必须接受选项对象,并允许将 groupsEnabledgroupsDisabled 传递给它。 这允许传输级别白名单( 比如,控制台列表),比如控制台应该只捕获 group1,但是文件传输应该捕获所有的日志消息

    log 函数需要传递 loggedObject,这是在 log() 被调用之后创建的对象。 它具有 meta 属性和 message ( 日志消息本身)。group ( 日志消息所属的组) 以及包含传入 logger.log() 调用的任何附加参数的properties 键。

    注意:查看 examples/example-json.js 以查看loggedObject的外观。

    下面是一个简单的传输定义:

    functionMyTransport ( options ){
     options = options || {};
     // Transport must set groupsEnabled and groupsDisabled to provide transport // level support for overriding what groups to log// (NOTE - the user does not need to pass in groupsEnabled, but the // transport must set these properties)this.groupsEnabled=options.groupsEnabled;
     this.groupsDisabled=options.groupsDisabled;
     // Transport specific settings// ------------------------------this.spacing=options.spacing===undefined?4:options.spacing;
     returnthis;
    }MyTransport.prototype.name='MyTransport';MyTransport.prototype.log=functionMyTransportLog( loggedObject ){
     // Do something with loggedObject returnthis;
    };

    有关工作传输的简单示例,请参见 lib/bragi/transports/ConsoleJSON

    运行测试

    尽管Bragi本身没有依赖关系,但是测试依赖于 mocha 和 chain。 安装开发依赖项( npm install -d )。 运行 npm test

    概念 behind Bragi

    驱动Bragi的一些核心概念是:

    • 通过设计,应该有很多对 log() inside的调用,应用程序的代码库不应该被删除。

    • 日志输出不应与对 log()的调用耦合。 应该很容易将 log() 调用的输出发送到控制台。文件或者远程主机。 让图书馆为某些类型的日志发送一个推送通知,这是很简单的。

    • 日志消息应该是结构化数据- 对于 Bragi,所有对 log()的调用都应该生成一个带有记录消息和一些元信息的JSON对象。 这使得使用日志更加容易,并允许与Graylog或者Kibana等第三方服务更好地集成

    • 日志库本身应该不关心日志,但是可以使用它们不费力地做任何事情。

    日志的可用性

    查看日志如何成为强大工具的概述。

    日志是一个强大且经常未充分利用的工具。 跟其他的一样有权衡。 在代码中持久记录日志语句的一些好处包括:

    • double作为显式文档在某些方面,它们类似于可以操作的注释
    • 使调试流程更容易调试
    • 重构中的助手
    • 帮助你维护代码所做的工作

    快乐日志记录 !


      framework  COL  log  color  nodejs  
    相关文章