Copland has an integrated logging system based on a slight variation of Ruby’s own “logger” library. In addition to the features of that library, Copland’s logging system provides:
- A logger factory for creating shared logger instances
- YAML-based configuration of the factory
- Customizable message formatting
Each registry instance has its own instance of
Copland::LogFactory. This provides a way to map a name to a logger instance, and allows each service point (for example) to have its own logger instance. This allows various logger settings to be tweaked per service-point.
For example, if I want debugging information to be logged for one service point, but not for another, I can specify the logging priority level for the one service point to include debug messages, and have such messages excluded for the other service point.
The log factory allows default values to be set for the priority level, date format string, and message format string, which will be applied to any logger that does not have a specific value set for those values. The log factory also allows configuration of the IO device to log to, the filename to log to, and various other (Logger-specific) data items (see the API documentation for
Copland::LogFactory for more information).
If you ever need to access the current log factory instance, you can get it from the registry as the
There are three ways to configure loggers. The first is programmatically, manually tweaking each log instance directly. The second is to pass configuration options to the registry itself when it is built, and the third is to use a configuration file.
To programmatically configure a logger, just obtain a handle to a logger instance and then tweak it via the accessor methods of the logger:
factory = registry.service( "copland.LogFactory" ) log = factory.get( "some.log.name" ) # Standard Logger attributes log.level = Logger::INFO log.progname = "different.log.name" log.datetime_format = "%Y%m%d" # Extended Logger attributes (provided by Copland) log.message_format = "[%-5p] %d %c: %m"
Note: programmatically changing the logger
progname does not change the name by which the logger is known to the factory!
In general, programmatic tweaking of the logger attributes as demonstrated above is not going to be the best way to do it. First of all, it is tedious, and bug prone. Secondly, it is difficult to know where the best place to do such work is, since you need to set those attributes before any other service tries to access that log.
The second approach is to pass logger configuration options to
Registry.build, when you create a registry instance:
registry = Copland::Registry.build( :log_device => STDOUT, :log_default_level => Logger::INFO, ... )
This gives you much greater flexibility than the previous approach, since it allows you to specify a greater array of options. The allowed options are:
||This is the name of the configuration file to use to configure the log factory. It defaults to “logger.yml”. (See the next section for more information.)|
||This is the IO (or pseudo-IO) object to write log messages to. If this option is specified,
||This is the name of the file to write log messages to. If this option is specified,
||This specifies the number of days before the log should be rolled. (This option is only useful when used with
||This should be either
||This specifies the maximum size of a log file. Once the log file gets larger than this value, the log will be rolled. (This option is only useful when used with
||This is the default date format string to use for the loggers that are created. It may be any string that is understood by
||This is the default message format string to use for the loggers that are created. It is a printf-styled string with special format specifiers—see the API documentation for
||This is the default level for each logger. Messages that are logged below this level (also “priority” or “severity”) will not be logged. By default, all messages are logged.|
||This is a hash. Each key should be a string containing a regular expression. For every logger whose name matches one of these patterns, the corresponding value will be used to define specific values for that logger. The value for each key must either be a string (in which case it is the name of the severity level to use), or a hash (containing any of the keys “level”, “date-format”, or “message-format”).|
Configuration via YAML
The third option (and the most flexible) is to use a YAML configuration file to define the parameters of the log factory and its loggers. By default, this file is called “logger.yml”, but you can specify a different logger configuration file via the
:log_config_file option to
Copland::Registry.build. By default, the configuration file must reside in current working directory, but you can specify an explicit path in the string you give to
The file has options that correspond to the configuration parameters described above:
--- filename: log/filename.log roll-age: 5 default-date-format: %Y%m%d%H%M%S default-message-format: %p %d %t %C: %m (%l) default-level: DEBUG levels: copland.*: WARN project.*: level: INFO date-format: %Y%m%d::%H%M%S message-format: %p %d: %m