Tor源码文件分析 — Log

  日志模块是Tor系统中一个非常重要的部件。它将Tor系统中的所有事件,分成不同的严重级别,分成不同的系统域,进行统一的日志处理。同时它还维护着一个日志记录链表。日志记录链表内存储的是所有日志需要输出的目标日志文件或目标日志输出位置。下文中我们会详细地对日志模块进行分析,并简要说明源文件中的各函数的简单作用。

1. 严重等级和域

  日志模块内定义了5个严重等级,其具体的设定如下:

/** Debug-level severity: for hyper-verbose messages of no interest to
 * anybody but developers. */
#define LOG_DEBUG   7
/** Info-level severity: for messages that appear frequently during normal
 * operation. */
#define LOG_INFO    6
/** Notice-level severity: for messages that appear infrequently
 * during normal operation; that the user will probably care about;
 * and that are not errors.
 */
#define LOG_NOTICE  5
/** Warn-level severity: for messages that only appear when something has gone
 * wrong. */
#define LOG_WARN    4
/** Error-level severity: for messages that only appear when something has gone
 * very wrong, and the Tor process can no longer proceed. */
#define LOG_ERR     3

  五个严重等级所对应的数字越小,说明他们的严重性越高。

  日志模块内同时定义了许多个域,用于记录日志时标记日志是系统中哪个域输出的日志:

/* Logging domains */

/** Catch-all for miscellaneous events and fatal errors. */
#define LD_GENERAL  (1u<<0)
/** The cryptography subsystem. */
#define LD_CRYPTO   (1u<<1)
/** Networking. */
#define LD_NET      (1u<<2)
/** Parsing and acting on our configuration. */
#define LD_CONFIG   (1u<<3)
/** Reading and writing from the filesystem. */
#define LD_FS       (1u<<4)
/** Other servers' (non)compliance with the Tor protocol. */
#define LD_PROTOCOL (1u<<5)
/** Memory management. */
#define LD_MM       (1u<<6)
/** HTTP implementation. */
#define LD_HTTP     (1u<<7)
/** Application (socks) requests. */
#define LD_APP      (1u<<8)
/** Communication via the controller protocol. */
#define LD_CONTROL  (1u<<9)
/** Building, using, and managing circuits. */
#define LD_CIRC     (1u<<10)
/** Hidden services. */
#define LD_REND     (1u<<11)
/** Internal errors in this Tor process. */
#define LD_BUG      (1u<<12)
/** Learning and using information about Tor servers. */
#define LD_DIR      (1u<<13)
/** Learning and using information about Tor servers. */
#define LD_DIRSERV  (1u<<14)
/** Onion routing protocol. */
#define LD_OR       (1u<<15)
/** Generic edge-connection functionality. */
#define LD_EDGE     (1u<<16)
#define LD_EXIT     LD_EDGE
/** Bandwidth accounting. */
#define LD_ACCT     (1u<<17)
/** Router history */
#define LD_HIST     (1u<<18)
/** OR handshaking */
#define LD_HANDSHAKE (1u<<19)
/** Heartbeat messages */
#define LD_HEARTBEAT (1u<<20)
/** Number of logging domains in the code. */
#define N_LOGGING_DOMAINS 21

/** This log message is not safe to send to a callback-based logger
 * immediately.  Used as a flag, not a log domain. */
#define LD_NOCB (1u<<31)

  每个域由其所占用的比特位来标识。

  在定义了严重等级与域之后,日志模块又定义了域掩码和域掩码数组:

/** Mask of zero or more log domains, OR'd together. */
typedef uint32_t log_domain_mask_t;

/** Configures which severities are logged for each logging domain for a given
 * log target. */
typedef struct log_severity_list_t {
  /** For each log severity, a bitmask of which domains a given logger is
   * logging. */
  log_domain_mask_t masks[LOG_DEBUG-LOG_ERR+1];
} log_severity_list_t;

  通过以上这三部分的说明,我们大致可以猜测,日志模块的分级分域输出的实现,就是根据严重级别以及域掩码的判断来实现的。作为一个普通的日志模块,其大致的功能只要是能将需要输出的日志信息,存放在一定的位置,方便管理员查看即可。按照这种简单的想法,似乎日志模块也就是如此这般便可。但是,实际上Tor系统内部的日志模块所具有的功能还相对复杂:临时日志功能;多重日志输出功能;日志回调功能。所以,我们还需要进一步分析。

2. 概述

  Tor系统的日志模块维护着一个日志输出列表,用于存储所有需要输出的日志存储位置。当一个日志消息到达,日志模块会遍历列表,一个一个比对其严重等级与域掩码是否符合对应输出的要求,如果符合,则输出,若不符合则跳过。多重日志输出功能就是通过这样的方式进行实现的。临时日志功能是Tor系统刚刚启动之时,还未读取配置文件中需要记录日志的日志文件信息,用于临时输出系统信息的功能。默认情况下,临时日志会被直接输出到终端上,也就是说其输出位置是stdout。而在系统成功启动日志系统,读取日志配置文件信息之后,就会关闭临时输出日志信息的位置,开启配置文件中要求记录日志的位置。

  我们先针对以上两个功能进行举例说明:

  系统刚刚启动之时,日志模块还未初始化完全,使用临时日志功能。日志输出列表如下:

      logfile  =  stdout(old)  –>  NULL

  系统成功读取配置文件,利用配置文件信息初始化日志模块之后,日志输出列表如下:

      logfile  =  stdout(new)  –>  file2  –>  file1 –>  NULL

  其相对应的配置文件关于日志管理部分的内容为:

    Log debug file1

    Log notice file2

    Log warn stdout

  也就是说,系统会通过配置文件内的配置,往日志输出列表内加入输出位置;删除临时输出位置。此处我们没有具体说出是先添加输出位置还是先删除临时输出位置,凭猜测应该是先添加输出位置,再删除临时输出位置。具体的先后请大家自行参看源码。

  当有日志消息需要输出只是,系统会遍历以上的logfile链表,匹配严重等级与域掩码,然后相应地输出日志到对应的文件或位置。

  以上谈论的是日志模块的两个主要功能,还有一个是日志信息的回调功能。这个功能和Tor系统的控制模块相关,在下文当中我们简要的描述,不会多讲,等到具体介绍控制模块的时候,我们会再深入地进行说明。

3. 全局变量

  日志模块的全局变量有一些,但是其中有部分是没有多大作用的。我们这里只列举出那些对日志模块功能起着很大作用的全局变量,对他们进行部分分析:

/** A mutex to guard changes to logfiles and logging. */
static tor_mutex_t log_mutex;                 //日志锁,用于互斥操作
/** True iff we have initialized log_mutex */
static int log_mutex_initialized = 0;                        //日志锁标志,用于标记日志锁是否初始化

/** Linked list of logfile_t. */
static logfile_t *logfiles = NULL;                           //日志输出位置链表
/** Boolean: do we report logging domains? */
static int log_domains_are_logged = 0;                       //日志输出时是否输出相对应的日志域
/** Log messages waiting to be replayed onto callback-based logs */
static smartlist_t *pending_cb_messages = NULL;              //延迟输出的回调消息链表,用于系统控制模块
/** NULL-terminated array of names for log domains such that domain_list[dom]
 * is a description of dom. */
static const char *domain_list[] = {                         //域列表,用于字符串与域对应数字之间的转换
  "GENERAL", "CRYPTO", "NET", "CONFIG", "FS", "PROTOCOL", "MM",
  "HTTP", "APP", "CONTROL", "CIRC", "REND", "BUG", "DIR", "DIRSERV",
  "OR", "EDGE", "ACCT", "HIST", "HANDSHAKE", "HEARTBEAT", NULL
};

  通过以上的解释,应该只对pending_cb_messages不大理解。为什么需要有这样的链表?为什么需要挂起日志?回调日志又是怎么回事?这个部分,我们留到之后分析控制模块之时回答。这里只做简要的说明:系统的控制模块有的时候对一些日志消息有浓厚的兴趣,他需要日志模块在某些日志产生的时候提醒他。如何进行提醒呢?控制模块在日志模块注册一个日志输出位置,其实不是真正的输出位置,他同时提供一个回调函数。当日志模块接收到对应的日志之时,就会通过回调函数通知控制模块,相应的日志已经出现。于是控制模块就可以进行控制操作。

4.函数说明

  init_logging

  parse_log_level

  parse_log_severity_config

  set_log_severity_config

  log_level_to_string

  初始化日志模块及基本工具函数;

  add_sys_log

  add_callback_log

  add_temp_log            –>  add_stream_log

  add_file_log                –>  add_stream_log

  往系统输出链表内添加日志输出位置的函数。由上述这些函数我们可以将输出位置的类型分为3类:sys,callback,stream。其中我们最常见的就是流类型。因为该类型就指代了我们平时所常见的输出位置:文件,标准输入输出等。

  flush_pending_log_callbacks

  处理挂起的回调日志的函数,分析控制模块之时我们会再次详细讲述这个部分。

  其他余下的函数其实大致都是对日志模块的小部分操作,与工具函数基本类似,分析到此处不必在过多得分析函数功能。我们可以凭照我们平时开发系统的经验,大致猜测出还需要什么函数或小功能以完善整个日志系统。最重要的函数,应该就是记录日志的操作函数。日志模块根据不同的严重等级,提供了不同的记录日志函数:

  log_debug

  log_info

  log_notice

  log_warn

  log_err

  但是其实,他们也只是对一个核心日志记录函数的上层封装,该函数就是:logv

  有兴趣的朋友可以自行查看logv函数的核心实现,其实现过程简单的说,就是根据不同的输出位置类型,执行不同的输出操作。