New logging interfaces

Configuration.txt

@@ -29,6 +29,7 @@ DaemonKit includes a couple of its own arguments that can be used:
 
   -e ENV (or --env ENV) to set the daemon environment
   --pid /path/to/pidfile to set the path to a pidfile
+  -l path (or --log path) to set the path for the log file
   -v shows the DaemonKit version
   -h shows a useful help message
 

History.txt

@@ -1,3 +1,10 @@
+== 0.1.7.5 2009-06-08
+
+* New AbstractLogger
+** Default Logger backend
+** SysLogLogger support
+* More documentation
+
 == 0.1.7.4 2009-06-05
 
 * Fixed bug with control script generator (thanks Sho Fukamachi)

Logging.txt

@@ -0,0 +1,92 @@
+= Logging from inside your daemon
+
+Proper logging inside your daemon process is critical, and daemon-kit
+provides you with a great logging facility to (ab)use.
+
+== Logging examples
+
+From anywhere in your code you can access the
+<em>DaemonKit.logger</em> instance, which is a configured
+DaemonKit::AbstractLogger. It is compatible with Ruby's Logger class
+but is much more verbose to help you gain some insight into your
+running process.
+
+  DaemonKit.logger.info( "Hello world" )
+
+This logs a 'Hello world' line to the log file, complete with the
+calling file name and line number. Log lines look something like this:
+
+  2009-06-07 23:21:30.248575 capd(32513) [INFO] initializer.rb:91: DaemonKit (0.1.7.4) booted, now running capd
+
+Log as much as you can, but be careful not to abuse the <em>info</em>
+level since your log files can become huge. For general processing
+hints, use the <em>debug</em> level.
+
+To log exceptions, use the special <em>exception</em> helper:
+
+  begin
+    # dangerous operation
+  rescue => e
+    DaemonKit.logger.exception( e )
+  end
+
+== Controlling logging in a running process
+
+Logging can be controlled in a running process, either via code or by
+sending UNIX signals to the running process.
+
+=== Changing log levels in your code
+
+Log levels can be toggled with the <em>level=</em> method:
+
+  DaemonKit.logger.level = :info
+
+Alternatively you can silence all the logging activity for a while
+using the silence helper:
+
+  DaemonKit.logger.silence do |logger|
+    # logger will only report :error or higher levels
+  end
+
+=== Changing log levels via UNIX signals
+
+Send your process the +USR1+ signal to toggle between <em>:debug</em>
+and <em>:info</em> log levels. Sending a +USR2+ signal will force the
+logger into <em>:debug</em> mode (+USR1+ will revert).
+
+== Support for log rotation
+
+Support for logrotate is baked right into daemon-kit. By sending your
+daemon a +HUP+ signal all the log files file be closed and re-opened
+again on first use. Here is an example logrotate configuration:
+
+  /path/to/daemon.log {
+    rotate 5
+    weekly
+    postrotate
+      kill -HUP `cat /path/to/daemon.pid`
+    endscript
+  }
+
+== Support for syslog logging
+
+If you have the
+SyslogLogger[http://seattlerb.rubyforge.org/SyslogLogger/] gem
+installed, you can have your process log to a UNIX syslog server. You
+can change the logging to syslog by either updating your
+<em>environment.rb</em> file like this:
+
+  config.log_path = :syslog
+
+Or by passing 'syslog' as the logfile argument when starting a daemon
+
+  $ ruby ./bin/daemon start -l syslog
+
+The SyslogLogger rdoc's provide configuration examples for configuring
+various UNIX syslog servers.
+
+== More logging information
+
+If you're running your daemon in the foreground (with the <em>run</em>
+command, you'll get copies of all the log messages on STDOUT, and thus
+voiding the need to tail log files the whole time.

Manifest.txt

@@ -1,6 +1,7 @@
 Configuration.txt
 Deployment.txt
 History.txt
+Logging.txt
 Manifest.txt
 PostInstall.txt
 README.rdoc
@@ -53,6 +54,7 @@ daemon_generators/nanite_agent/templates/config/nanite.yml
 daemon_generators/nanite_agent/templates/lib/actors/sample.rb
 daemon_generators/nanite_agent/templates/libexec/daemon.rb
 lib/daemon_kit.rb
+lib/daemon_kit/abstract_logger.rb
 lib/daemon_kit/amqp.rb
 lib/daemon_kit/application.rb
 lib/daemon_kit/arguments.rb
@@ -88,6 +90,7 @@ script/console
 script/destroy
 script/generate
 script/txt2html
+spec/abstract_logger_spec.rb
 spec/argument_spec.rb
 spec/config_spec.rb
 spec/daemon_kit_spec.rb

lib/daemon_kit.rb

@@ -7,19 +7,20 @@
   $:.include?( File.dirname(__FILE__).to_absolute_path )
 
 module DaemonKit
-  VERSION = '0.1.7.4'
-
-  autoload :Initializer, 'daemon_kit/initializer'
-  autoload :Application, 'daemon_kit/application'
-  autoload :Arguments,   'daemon_kit/arguments'
-  autoload :Config,      'daemon_kit/config'
-  autoload :Safety,      'daemon_kit/safety'
-  autoload :PidFile,     'daemon_kit/pid_file'
-
-  autoload :Cron,        'daemon_kit/cron'
-  autoload :Jabber,      'daemon_kit/jabber'
-  autoload :AMQP,        'daemon_kit/amqp'
-  autoload :Nanite,      'daemon_kit/nanite'
+  VERSION = '0.1.7.5'
+
+  autoload :Initializer,    'daemon_kit/initializer'
+  autoload :Application,    'daemon_kit/application'
+  autoload :Arguments,      'daemon_kit/arguments'
+  autoload :Config,         'daemon_kit/config'
+  autoload :Safety,         'daemon_kit/safety'
+  autoload :PidFile,        'daemon_kit/pid_file'
+  autoload :AbstractLogger, 'daemon_kit/abstract_logger'
+
+  autoload :Cron,   'daemon_kit/cron'
+  autoload :Jabber, 'daemon_kit/jabber'
+  autoload :AMQP,   'daemon_kit/amqp'
+  autoload :Nanite, 'daemon_kit/nanite'
 
   class << self
     def logger