kronoTwist version 1.1
log rotation program in Java
by Andrew Penhorwood - www.kaleo.biz

THE SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY WHATSOEVER.

************************************************************************************************

Reads data in from standard input and writes data out to a filename derived from the input template.  Normal usage will be programs that write log data out to standard output.  You just pipe '|' that data to kronoTwist with your filename template and away it goes recording that log data.  Files are created as needed along with directories.  On each rotation period the filename template is re-evaluated and the new file and/or directories are created without missing any of the log data in the process.  The input and output processes are separate threads in Java.  They use a data object to communicate that is thread safe.  If no log data is produces during the rotation period a log is still created.  Timing is as accurate as the hardware the kronoTwist is running on.  I have found it to work on the second to millisecond level during testing.

The Java Runtime Environment 1.3.1 or higher must be installed for kronoTwist to function.  (www.java.sun.com).  No need to set class paths as the kronoTwist.exe file will lookup the JVM information.

You need both the kronoTwist.exe file and the kronoTwist.jar file in the same directory to run the program.  The .jar file contains all of the .class files and the original .java source files.

kronoTwist is licensed under the Kaleo Freeware License agreement.  A copy is included with this package.

For the latest version of kronoTwist visit www.kaleo.biz - go to the download section.

************************************************************************************************

Usage: kronoTwist [/header[=switch]] [/append[=switch]] [/rate[=switch]] /file=filename

##### options 

/?       - display this help information (overrides all other switches except /version)
/version - displays kronoTwist version and exits (overrides all other switches except /?)

/h | /header - write a header section in output file
     new     - write a header in all newly created files
     append  - write a timestamp when 1st appending to files
     off     - (default) do not write any header information
     header without switches is the same as /header=new,append

/a | /append - if filename already created this will append to that file
     on      - (default) append to existing file
     off     - create new file with extension -a to -z (ie filename-a.log)
     append without switches is the same as /append=on

/r | /rate - use rotation rate not derived from filename
     xxxD    - set rate to xxx days (ie 2D, 14D or 462D)
     xxxW    - set rate to xxx weeks (ie 2W, 6W or 12W)
     xxxM    - set rate to xxx Months (ie 2M, 3M or 36M)
     xxxh    - set rate to xxx hours (ie 2h, 12h or 20h)
     xxxm    - set rate to xxx minutes (ie 5m, 15m, 90m or 135m)
     xxxs    - set rate to xxx seconds (ie 5s, 30s or 45s)
     /rate without switches is equal to NEVER rotate
     
/f | /file - filename to be created and used for rotation rate

  note: most switches with | use zero padding based on number of characters
        [ie %J = 1-366 or %JJ = 01-366 or %JJJ = 001-366]

     %J | JJ | JJJ - day in year (1-366) (Julian date) [zero padded]
     %DDDD         - full text day in week (Sunday .. Saturday) 
     %DDD          - abbreviated day in week (Sun .. Sat)
     %D | DD       - day in month (1-31) [zero padded]
     %W | WW       - week in year (1-53) [zero padded]
     %MMMM         - full text month (January .. December)
     %MMM          - abbreviated month (Jan .. Dec)
     %M|MM         - month (1-12) [zero padded]
     %YYYY         - full century year (2003)
     %YY           - year without century (03)
     %H | HH       - hour (1-23) (24 hour clock) [zero padded]
     %h | hh       - hour (1-12) (12 hour clock) [zero padded]
     %a | am | AM  - AM or PM marker (sames as p|pm|PM)
     %p | pm | PM  - AM or PM marker (sames as a|am|AM)
     %m | mm       - minutes in hour (1-59) [zero padded]
     %s | ss       - seconds in minute (1-59) [zero padded]
     %S | SS | SSS - milliseconds in second (1-999) [zero padded]
     /             - escape character (use: %MM/My.log = 12My.log)
     /%            - produces a % in filename
     //            - produces a / in filename

##### notes
 
 1.  kronoTwist is normally used with a pipe '|' on the command line
 2.  Any directories in filename that do NOT exist will be created.
 3.  rotation rates are figured to the next start period
      example - I start a log at 3pm.  It is set to rotate every day.  The next log will be created at midnight.
                since this is the start of the next day.  The first log will not be a complete day due to
                the processing starting at 3pm.  All other files will cover a complete day until the process
                is stopped.
     
 4.  /rate option always overrides the filename rotation rate
 5.  NEVER rotate is equal to 100 years.  Seemed like never to me. ;-)

##### example 

MyProgram|kronoTwist /header=new /file=c:\log\%MMMM\%YYYY%MM%DD.log

  * creates [ c:\log\June\20030617.log ] with a header from the standard output of MyProgram.exe
  * as long as MyProgram runs a new log will be created every day.  Logs will rotate on the begining
    of the next day (midnight).
  
MyProgram|kronoTwist /rate=2D /file=c:\log\%MMMM\%YYYY%MM%DD.log

  * creates [ c:\log\June\20030617.log ] with a header from the standard output of MyProgram.exe
  * a new log will be created every 2 days starting at midnight.
  
##### Special Consideration

  * Apache 2.0.xx
  
     1. kronoTwist does work well with Apache but the header information might seem strange.  Apache launches multiple processes when it executes which all try to write to the same file at the same time.  The data will not be mixed and no log data will be missed but the header might not be the first item in the file.  Normally the header is the first item but I have experienced in testing "::append header" lines before the "new header".  This does not affect the order of log lines as the each log line is written by the child process and not the parent process in Apache.
  
     2. If used with the "error log" you will see multiple "::append" lines even thought Apache just started.  Again this is due to the number of processes that Apache starts.  All data is being written to the log file.  The same behavior is happening with other log rotation programs they just don't report when they append to a file.
     
     3. On a normal windows system there will be 4 kronoTwist processes running.  When Apache starts it launches a parent process for the access log and the error log.  Then it lauches a child process for each of these logs also.  Each process will launch a copy of kronoTwist.  In testing the parent Access log process produces no log entries only the child process.  The Error log is different in that each process produces log entries depending on the error type.  It is possible to kill the Access kronoTwist process for the Parent process without effecting the log output.
