logging_hivenet模块说明¶
logging_hivenet模块重新封装了python的logging模块，提供一个更便于使用的日志处理类。
logging_hivenet的简单使用¶
1、装载要使用的对象
import HiveNetCore.logging_hivenet as simple_log
2、程序本地创建“logger.conf”文件，修改配置文件为自己希望的内容
注意：conf文件中请不要含中文内容，原因是目前的程序对中文处理存在转码问题（问题待解决）
主要修改的参数如下：
（1）[handler_FileHandler]下的args参数：
第1个参数是日志文件名（可以带路径），日志程序会自动在扩展名前补充日期；
第2个参数固定为追加模式；
第3个参数为自动转存的文件大小，单位为byte；
第4个参数为自动转存时，超过多少个文件后以覆盖方式记录（不会再新增）
（2）[formatters]下的format参数，该参数定义了日志的格式
补充说明：也可以是json或xml文件，内容都一样，只是格式不同，配置说明在后面介绍
3、实例化Logger对象并使用
# 实例化对象，根据需要传入不同参数
_logger = simple_log.Logger(...)
# 写日志
_logger.log(simple_log.INFO, '要写入的日志')
# 其他写入方式
_logger.info('要写入的INFO日志')
_logger.debug('要写入的Debug日志')
4、使用注意问题
logger类是全局共享的，即如果loggername、handler的配置名一样，建立多个logger类且进行调整的情况下会互相干扰，因此如果需要实例化多个logger，则建议配置名和handler名有所区分
Python默认的FileHandler是线程安全的（支持多线程），但不是进程安全（不支持启动多进程记录同一日志），如果需要支持多进程，需要使用第三方的FileHandler，使用方式如下：
（1）pip install ConcurrentLogHandler
（2）修改日志配置文件的class=handlers.RotatingFileHandler为class=handlers.ConcurrentRotatingFileHandler
日志调用特殊参数说明¶
Logger初始化参数
@param {EnumLoggerName|string} logger_name=EnumLoggerName.Console - 输出日志类型，默认的3个类型如下：Console-输出到屏幕,File-输出到文件,ConsoleAndFile-同时输出到屏幕和文件；如果自己自定义了日志模块名，可以直接使用字符串方式传值使用（例如'myLoggerName'）
@param {string} json_str=None - 当日志配置方式为JSON_STR时使用，配置的字符串,如果不串则默认使用_LOGGER_DEFAULT_JSON_CONSOLE_STR的值
@param {bool} auto_create_conf=True - 如果配置方式是文件的情况，指定是否利用默认的参数自动创建配置文件（找不到指定的配置文件时），默认为True
@param {bool} is_create_logfile_by_day=True - 指定是否按天生成新的日志文件，默认为True
@param {int} call_fun_level=0 - 指定log函数输出文件名和函数名的层级，当自己对日志函数再封装了几层的情况下，无法打印到实际所需要登记的函数时，可以指定从向上几级来获取真实调用函数；0代表获取直接调用函数；1代表获取直接调用函数的上一级
@param {string} logfile_path='' - 日志输出文件的路径（含文件名），如果已有配置文件的情况下该参数无效，不传值时代表使用'log/程序名.log'来定义输出文件的路径
log写日志
@param {int} - 输出日志的级别，可以使用simple_log.INFO这类值，也可以直接使用标准logging.INFO这样的传值
@param {**kwargs} args - 通用日子类的kwargs参数，以下为特殊参数的说明
extra {dict} - 用于传递日志上下文的字典，可用于额外添加一些上下文内容
例如可传入{'ip': '113.208.78.29', 'username': 'Petter'}，这样当Formatter为
'%(asctime)s - %(name)s - %(ip)s - %(username)s - %(message)s'时可以正常输出日志值
以下是simple_log定义的一些特殊上下文：
callFunLevel {int} - 日志中输出的函数名（文件名）所属层级：
0 - 输出调用本函数的函数名（文件名）
1 - 输出调用本函数的函数的上1级函数的函数名（文件名）
n - 输出调用本函数的函数的上n级函数的函数名（文件名）
dealMsgFun {function} - 自定义日志内容修改函数，可以在输出日志前动态修改日志内容（msg）
函数格式为funs(topic_name, record){return msg_string}，返回生成后的日志msg内容
topicName {string} - 日志主题，与dealMsgFun配套使用
日志配置文件详解¶
以下以INI文件的格式说明配置项的内容，其他格式的是同样道理：
###############################################
# 以下部分定义logger模块，root是父类，必需存在的，其它的是自定义的模块名（例子中的模块名是默认创建的，使用者可以自行定义其他模块名）
# logging.getLogger(模块名称) 相当于向根据指定模块名的定义实例化一个日志操作对象
# 每个[logger_模块名称] 实际定义了一个模块名称和对应的处理句柄类
# level 日志输出级别，有DEBUG、INFO、WARNING、ERROR、CRITICAL，可设置不同级别进行日志的过滤
# handlers 处理句柄类，一个日志模块可以引用多个处理句柄，用逗号分开，用来实现同一日志向多个地方输出
# qualname logger名称，应用程序通过 logging.getLogger获取。对于不能获取的名称，则记录到root模块
# propagate 是否继承父类的log信息，0:否 1:是
###############################################
[loggers]
keys=root,Console,File,ConsoleAndFile
[logger_root]
level=DEBUG
handlers=
[logger_Console]
level=DEBUG
handlers=ConsoleHandler
[logger_File]
handlers=FileHandler
qualname=File
propagate=0
[logger_ConsoleAndFile]
handlers=ConsoleHandler,FileHandler
qualname=ConsoleAndFile
propagate=0
###############################################
# 以下部分定义处理句柄及相关参数：
# [handlers] 指定配置里定义的句柄名清单
# [handler_句柄名] 定义了具体句柄的具体传入参数，简要说明如下：
# class - 句柄的类对象路径（按照python标准访问类的形式），要求在代码中必须能通过该路径访问类
# level - 句柄对应的日志级别，可设置不同级别进行日志的过滤
# formatter - 指定句柄对应的日志格式定义，为[formatters]章节的格式名
# args - 句柄类初始化的传入参数，按照不同的句柄有不同的定义
#
# 可以使用python自带的句柄类、第三方库中的句柄类，也可以自行开发自己的句柄类，部分官方句柄类说明如下：
# StreamHandler : 使用这个Handler可以向类似与sys.stdout或者sys.stderr的任何文件对象(file object)输出信息。它的构造函数是：
# StreamHandler([strm])
# 其中strm参数是一个文件对象。默认是sys.stderr
# FileHandler : 和StreamHandler类似，用于向一个文件输出日志信息。不过FileHandler会帮你打开这个文件。它的构造函数是：
# FileHandler(filename[,mode])
# filename是文件名，必须指定一个文件名。
# mode是文件的打开方式。参见Python内置函数open()的用法。默认是’a'，即添加到文件末尾。
# handlers.RotatingFileHandler : 这个Handler类似于上面的FileHandler，但是它可以管理文件大小。当文件达到一定大小之后，它会自动将当前日志文件改名，然后创建一个新的同名日志文件继续输出。比如日志文件是chat.log。当chat.log达到指定的大小之后，RotatingFileHandler自动把文件改名为chat.log.1。不过，如果chat.log.1已经存在，会先把chat.log.1重命名为chat.log.2...;最后重新创建 chat.log，继续输出日志信息。它的构造函数是：
# RotatingFileHandler( filename[, mode[, maxBytes[, backupCount]]])
# 其中filename和mode两个参数和FileHandler一样。
# maxBytes用于指定日志文件的最大文件大小。如果maxBytes为0，意味着日志文件可以无限大，这时上面描述的重命名过程就不会发生。
# backupCount用于指定保留的备份文件的个数。比如，如果指定为2，当上面描述的重命名过程发生时，原有的chat.log.2并不会被更名，而是被删除。
###############################################
[handlers]
keys=ConsoleHandler,FileHandler
[handler_ConsoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout,)
[handler_FileHandler]
class=handlers.RotatingFileHandler
level=INFO
formatter=simpleFormatter
args=('myapp.log', 'a', 10*1024*1024, 1000)
###############################################
# 以下部分定义输出的格式和内容:
# [formatters] 指定配置里定义的格式名清单
# [formatter_格式名] 为具体格式名的配置，里面有两个参数：
# format - 定义输出日志的默认信息（前缀），可选的信息项包括：
# %(levelno)s: 打印日志级别的数值
# %(levelname)s: 打印日志级别名称
# %(pathname)s: 打印当前执行函数所在文件的路径
# %(filename)s: 打印当前执行函数所在的文件名
# %(funcName)s: 打印日志的当前函数名
# %(lineno)d: 打印日志的当前行号
# %(asctime)s: 打印日志的时间
# %(millisecond)s: 打印日志的时间(毫秒，不适用于官方的logging)
# %(thread)d: 打印线程ID
# %(threadName)s: 打印线程名称
# %(process)d: 打印进程ID
# %(message)s: 打印日志信息
# datefmt - 定义日期时间（asctime）的输出格式，默认为%Y-%m-%d %H:%M:%S,uuu
# %y 两位数的年份表示（00-99）
# %Y 四位数的年份表示（000-9999）
# %m 月份（01-12）
# %d 月内中的一天（0-31）
# %H 24小时制小时数（0-23）
# %I 12小时制小时数（01-12）
# %M 分钟数（00=59）
# %S 秒（00-59）
# %a 本地简化星期名称
# %A 本地完整星期名称
# %b 本地简化的月份名称
# %B 本地完整的月份名称
# %c 本地相应的日期表示和时间表示
# %j 年内的一天（001-366）
# %p 本地A.M.或P.M.的等价符
# %U 一年中的星期数（00-53）星期天为星期的开始
# %w 星期（0-6），星期天为星期的开始
# %W 一年中的星期数（00-53）星期一为星期的开始
# %x 本地相应的日期表示
# %X 本地相应的时间表示
# %Z 当前时区的名称
# %% %号本身
# 注意：python并未给出毫秒的占位符，因此如果datefmt为空输出格式才有毫秒，如果要自己输出，请采用%(millisecond)s占位符
###############################################
[formatters]
keys=simpleFormatter
[formatter_simpleFormatter]
format=[%(asctime)s.%(millisecond)s][%(levelname)s][PID:%(process)d][TID:%(thread)d][FILE:%(filename)s][FUN:%(funcName)s]%(message)s
datefmt=%Y-%m-%d %H:%M:%S
通过队列日志句柄实现异步日志处理¶
可以通过simple_log.QueueHandler来实现异步日志处理，QueueHandler可将日志信息写入内存队列中，然后通过对内存队列的日志项进行处理来实现异步记录日志。
使用步骤如下：
1、配置Logger句柄，让日志写入队列中¶
传入的4个参数说明如下：
queue - 要写入的队列对象，如果不传值，代表由handler自行生成一个内存队列；如果传入的是字符串，则代表该字符串为可获取到队列对象的变量名字符串，handler将自动根据该字符串获取队列对象
topic_name - 默认的日志主题，当写日志的时候没有传topicName的扩展信息时使用
is_deal_msg - 是否处理日志格式，true代表直接生成完整的日志，将日志字符串写入队列；false代表不直接生成完整的日志消息，而是将record对象放入队列（待后面的程序自动处理）
error_queue_size - 通过start_logging方法写日志时，遇到异常时记录错误信息的队列大小, 如果错误信息数量超过大小，会自动删除前面的数据，0代表不限制大小
# 对于json格式的日志配置，句柄配置参考如下
# 第1个配置会在写日志的时候直接将格式化后的日志字符串写入队列
# 第2个配置不直接格式化日志字符串，而是将包含日志所有信息的record对象送入队列，可在处理时再格式化
"handlers": {
"QueueMsgHandler": {
"class": "HiveNetCore.logging_hivenet.QueueHandler",
"level": "DEBUG",
"formatter": "simpleFormatter",
"queue": "",
"topic_name": "",
"is_deal_msg": true,
"error_queue_size": 20
},
"QueueRecordHandler": {
"class": "HiveNetCore.logging_hivenet.QueueHandler",
"level": "DEBUG",
"formatter": "simpleFormatter",
"queue": "",
"topic_name": "",
"is_deal_msg": false,
"error_queue_size": 20
}
}
# 对于ini格式的日志配置，句柄配置参考如下
[QueueMsgHandler]
class=HiveNetCore.logging_hivenet.handler_queueHandler
level=DEBUG
formatter=logstashFormatter
args=("queue_var_name", "topic_name", true, 20)
[QueueRecordHandler]
class=HiveNetCore.logging_hivenet.handler_queueHandler
level=DEBUG
formatter=logstashFormatter
args=("queue_var_name", "topic_name", false, 20)
2、使用配置生成simple_log.Logger对象¶
# 配置中的QueueMsg指定使用QueueMsgHandler
queue_logger = simple_log.Logger(logger_name='QueueMsg',
json_str=_LOGGER_QUEUE_MSG_JSON_STR)
或
# 配置中的QueueRecord指定使用QueueRecordHandler
queue_logger = simple_log.Logger(logger_name='QueueRecord',
json_str=_LOGGER_QUEUE_MSG_JSON_STR)
3、按正常情况使用Logger记录日志¶
# 记录日志，简单模式
queue_logger.log(simple_log.INFO, 'INFO msg')
# 记录日志，通过extra传入特殊信息，示例中的topicName用于指定日志的topic_name；name2Obj为自定义传入对象，对于QueueRecordHandler的情况，可以自定义日志内容处理函数，通过record.name2Obj访问并使用对象生成日志内容
queue_logger.log(
simple_log.ERROR, 'ERROR msg',
extra={
'topicName': 'name3',
'name2Obj': ['a', 'b', 'c', 'd']
}
)
4、处理队列的日志信息¶
可以通过Logger.base_logger.handlers[0]获取handler对象，然后通过handler.queue访问队列，取到消息项进行相应的处理，消息项的格式如下：
queue_obj.levelno {int} : 日志级别，值说明参考logging.INFO这些值
queue_obj.topic_name {string} : 日志主题标识（用于使用方区分日志来源）,注意’default’为保留的标识名
queue_obj.msg {string} : 已格式化后的日志内容, is_deal_msg为True时有效
queue_obj.record {object} : 未格式化的日志相关信息，其中record.msg为要写入的日志’%(message)s’, is_deal_msg为False时有效
logging.QueueHandler也提供了对队列日志自动处理的方法，通过handler.start_logging启动后端线程自动处理队列中的日志数据，相关参数的定义如下：
@param {dict} loggers_or_funs - 要写入的日志logger对象列表(或处理函数列表), key为topic_name, value为对应的处理日志类(HiveNetCore.logging_hivenet.Logger)或处理函数
其中'default'为默认日志处理类或处理函数，如果不传入则代表匹配不到的topic_name不进行处理，规则如下：遇到日志项的topic_name在列表中不存在，先找'default'的日志对象进行处理，如果传入的日志对象清单中没有'default'，则不进行该日志项的处理
如果传入的是处理函数，格式为funs(levelno, topic_name, msg){...}
注意：如果为logger，则所传入的日志对象的formatter将统一修改为'%(message)s'，因此该日志对象注意不要与其他日志处理共用；字典里可以支持logger和fun并存，只是如果存在fun的情况，应注意formatters的取值
@param {int} thread_num=1 - 处理队列对象的线程数
@param {dict} deal_msg_funs={} - 处理record的函数(形成msg部分内容), 当is_deal_msg为False时有效, key为topic_name, value为对应的日志内容生成函数，搜索函数的规则与loggers一样，处理函数的定义应如下：func(topic_name, record) {return msg}
@param {dict} formatters=None - is_deal_msg为False时，用于格式化record的Formatter，key为topic_name，value为该topic_name的Formatter，搜索格式对象的规则与loggers一样，如果formatters=None，代表自动获取loggers的Formatter形成该字典
提醒：如果loggers_or_funs对应的处理对象为Logger，则会根据Logger的配置进行日志的实际输出处理；如果处理对象为函数，则执行函数进行自定义的日志处理（例如发送到远程服务器）