## ## logging.py ## Login : ## Started on Mon Jun 13 01:25:07 2011 Uli Fouquet ## $Id$ ## ## Copyright (C) 2011 Uli Fouquet ## This program is free software; you can redistribute it and/or modify ## it under the terms of the GNU General Public License as published by ## the Free Software Foundation; either version 2 of the License, or ## (at your option) any later version. ## ## This program is distributed in the hope that it will be useful, ## but WITHOUT ANY WARRANTY; without even the implied warranty of ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ## GNU General Public License for more details. ## ## You should have received a copy of the GNU General Public License ## along with this program; if not, write to the Free Software ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ## """ Convenience stuff for logging. Main component of :mod:`waeup.sirp.utils.logging` is a mix-in class :class:`waeup.sirp.utils.logging.Logger`. Classes derived (also) from that mix-in provide a `logger` attribute that returns a regular Python logger logging to a rotating log file stored in the datacenter storage path. Deriving components (classes) should set their own `logger_name` and `logger_filename` attribute. The `logger_name` tells under which name the logger should be registered Python-wise. This is usually a dotted name string like ``waeup.sirp.${sitename}.mycomponent`` which should be unique. If you pick a name already used by another component, trouble is ahead. The ``${sitename}`` chunk of the name can be set literally like this. The logger machinery will turn it into some real site name at time of logging. The `logger_filename` attribute tells how the logfile should be named. This should be some base filename like ``mycomponent.log``. Please note, that some logfile names are already used: ``main.log``, ``applications.log``, and ``datacenter.log``. The `Logger` mix-in also cares for updating the logging handlers when a datacenter location moves. That means you do not have to write your own event handlers for the purpose. Just derive from `Logger`, set your `logger_name` and `logger_filename` attribute and off you go:: from waeup.sirp.utils.logger import Logger class MyComponent(object, Logger): # Yes that's a complete working class logger_name = 'waeup.sirp.${sitename}.mycomponent logger_filename = 'mycomponent.log' def do_something(self): # demomstrate how to use logging from methods self.logger.info('About to do something') try: # Do something here except IOError: self.logger.warn('Something went wrong') return self.logger.info('I did it') As you can see from that example, methods of the class can log messages simply by calling `self.logger`. The datacenter and its storage are created automatically when you create a :class:`waeup.sirp.app.University`. This also means that logging with the `Logger` mix-in will work only inside so-called sites (`University` instances put into ZODB are such `sites`). Other components in this module help to make everything work. """ import os import grok import logging from string import Template from zope import schema from zope.component import queryUtility from zope.interface import Interface, Attribute, implements from waeup.sirp.interfaces import IDataCenter, IDataCenterStorageMovedEvent #: Default logfile size MAX_BYTES = 5 * 1024 ** 2 #: Default num of backup files BACKUP_COUNT = 5 class ILogger(Interface): logger_name = schema.TextLine( title = u'A Python logger name') logger_filename = schema.TextLine( title = u'A filename for the log file to use (basename)') logger = Attribute("Get a Python logger instance already set up") def logger_setup(logger): """Setup a logger. `logger` is an instance of :class:`logging.Logger`. """ def logger_get_logfile_path(): """Get path to logfile used. Return `None` if the file path cannot be computed. """ def logger_get_logdir(): """Get the directory of the logfile. Return `None` if the directory path cannot be computed. """ class Logger(object): """Mixin-class that for logging support. Classes that (also) inherit from this class provide support for logging with waeup sites. By default a `logger` attribute is provided which returns a regular Python logger. This logger has already registered a file rotating log handler that writes log messages to a file `main.log` in datacenters ``log/`` directory. This is the main log file also used by other components. Therefore you can pick another filename by setting the `logger_filename` attribute. All methods and attributes of this mix-in start with ``logger_`` in order not to interfere with already existing names of a class. Method names do not follow the usual Zope habit (CamelCase) but PEP8 convention (lower_case_with_underscores). """ #: The filename to use when logging. logger_filename = 'main.log' #: The Python logger name used when #: logging. ``'waeup.sirp.${sitename}'`` by default. You can use the #: ``${sitename}`` placeholder in that string, which will be #: replaced by the actual used site name. logger_name = 'waeup.sirp.${sitename}' implements(ILogger) @property def logger(self): """Get a logger instance. Returns a standard logger object as provided by :mod:`logging` module from the standard library. Other components can use this logger to perform log entries into the logfile of this component. The logger is initialized the first time it is called. The logger is only available when used inside a site. .. note:: The logger default level is :data:`logging.WARN`. Use :meth:`logging.Logger.setLevel` to set a different level. """ site = grok.getSite() sitename = getattr(site, '__name__', None) loggername = Template(self.logger_name).substitute( dict(sitename='%s' % sitename)) logger = logging.getLogger(loggername) if site is None or sitename is None: # Site not added to ZODB yet. Log to commandline return logger if len(logger.handlers) != 1: handlers = [x for x in logger.handlers] for handler in handlers: handler.flush() handler.close() logger.removeHandler(handler) logger = self.logger_setup(logger) return logger def logger_setup(self, logger): """Setup logger. The logfile will be stored in the datacenter logs/ dir. """ filename = self.logger_get_logfile_path() if filename is None: return collector = queryUtility(ILoggerCollector) if collector is not None: site = grok.getSite() collector.registerLogger(site, self) # Create a rotating file handler logger. handler = logging.handlers.RotatingFileHandler( filename, maxBytes=MAX_BYTES, backupCount=BACKUP_COUNT) formatter = logging.Formatter( '%(asctime)s - %(levelname)s - %(message)s') handler.setFormatter(formatter) # Don't send log msgs to ancestors. This stops displaying # logmessages on the commandline. logger.propagate = False logger.addHandler(handler) return logger def logger_get_logfile_path(self): """Get the path to the logfile used. Returns the path to a file in local sites datacenter ``log/`` directory (dependent on :meth:`logger_get_logdir`) and with :attr:`logger_filename` as basename. Override this method if you want a complete different computation of the logfile path. If you only want a different logfile name, set :attr:`logger_filename`. If you only want a different path to the logfile override :meth:`logger_get_logdir` instead. Returns ``None`` if no logdir can be fetched. .. note:: creates the logfile dir if it does not exist. """ logdir = self.logger_get_logdir() if logdir is None: return None return os.path.join(logdir, self.logger_filename) def logger_get_logdir(self): """Get log dir where logfile should be put. Returns the path to the logfile directory. If no site is set, ``None`` is returned. The same applies, if the site has no datacenter. If the dir dies not exist already it will be created. Only the last part of the directory path will be created. """ site = grok.getSite() if site is None: return None datacenter = site.get('datacenter', None) if datacenter is None: return None logdir = os.path.join(datacenter.storage, 'logs') if not os.path.exists(logdir): os.mkdir(logdir) return logdir def logger_logfile_changed(self): """React on logfile location change. If the logfile changed, we can set a different logfile. While changing the logfile is a rather critical operation you might not do often in production use, we have to cope with that especially in tests. What this method does by default (unless you override it): - It fetches the current logger and - Removes flushes, closes, and removes all handlers - Sets up new handler(s). All this, of course, requires to be 'in a site'. Use this method to handle moves of datacenters, for instance by writing an appropriate event handler. """ logger = self.logger self.logger_shutdown() self.logger_setup(logger) return def logger_shutdown(self): """Remove all specific logger setup. """ logger = self.logger handlers = [x for x in logger.handlers] for handler in handlers: handler.flush() handler.close() logger.removeHandler(handler) collector = queryUtility(ILoggerCollector) if collector is not None: collector.unregisterLogger(grok.getSite(), self) return class ILoggerCollector(Interface): def getLoggers(site): """Return all loggers registered for `site`. """ def registerLogger(site, logging_component): """Register a logging component residing in `site`. """ def unregisterLogger(site, logging_component): """Unregister a logger. """ class LoggerCollector(dict, grok.GlobalUtility): """A global utility providing `ILoggerCollector`. A logging collector collects logging components. This helps to inform them when a logfile location changes. Logging components are registered per site they belong to. """ implements(ILoggerCollector) def getLoggers(self, site): name = getattr(site, '__name__', None) if name is None: return [] if name not in self.keys(): return [] return self[name] def registerLogger(self, site, logging_component): name = getattr(site, '__name__', None) if name is None: return if not name in self.keys(): # new component self[name] = [] if logging_component in self[name]: # already registered return self[name].append(logging_component) return def unregisterLogger(self, site, logging_component): name = getattr(site, '__name__', None) if name is None or name not in self.keys(): return if logging_component not in self[name]: return self[name].remove(logging_component) return @grok.subscribe(IDataCenter, IDataCenterStorageMovedEvent) def handle_datacenter_storage_move(obj, event): """Event handler, in case datacenter storage moves. By default all our logfiles (yes, we produce a whole bunch of it) are located in a ``log/`` dir of a local datacenter, the datacenter 'storage'. If this path changes because the datacenter is moved an appropriate event is triggered and we can react. Via the global ILoggerCollector utility, a small piece that allows self-registering of logging components, we can lookup components whose logfile path has to be set up anew. Each component we call has to provide ILogger or, more specific, the :meth:`logger_logfile_changed` method of this interface. """ site = grok.getSite() if site is None: return collector = queryUtility(ILoggerCollector) loggers = collector.getLoggers(site) for logger in loggers: if hasattr(logger, 'logger_logfile_changed'): logger.logger_logfile_changed() return