=========================
Differences from Original
=========================

-next_run is determined based on the previous next_run and not based on when the job is actually run. This prevents jobs from slowly running later and later.
-All job runs are now logged
-Logs now record start and end time of jobs
-If stderr is emitted from job, the output will be logged to a 'chronograph' logger
-Added South migrations

===========
Chronograph
===========

Chronograph is a simple application that allows you to control the frequency at
which a Django management command gets run.

To help explain how this is useful, let's consider a simple example.  Say you've
written an application that displays weather on your site.  You've written a
custom management command that you can execute which updates the weather::

    python manage.py update_weather

You would like to be able to run this command every hour so that you always have
the latest weather information displayed on your site.  Rather than having to
edit your crontab, ``cronograph`` allows you to simply add this functionality
via your admin.

Installing Chronograph
======================

Installing ``chronograph`` is pretty simple.  First add it into ``INSTALLED_APPS``
in your ``settings.py`` file.  If you're running a version of Django older than
revision 9739 (basically anything after 1.0 but before 1.1), then you'll need to
add the following to your project's ``urls.py``::
  
	url(r'^admin/chronograph/job/(?P<pk>\d+)/run/$',
		'chronograph.views.job_run', name="chronograph_job_run"),

NOTE: make sure you place this *BEFORE* the root admin site include.  Your
``urls.py`` should then look something like::

  ...
  url(r'^admin/chronograph/job/(?P<pk>\d+)/run/$',
	  'chronograph.views.job_run', name="admin_chronograph_job_run"),
  ('^admin/(.*)', admin.site.root),
  ...

After this run `syncdb``.  The only thing left to do is set up a periodic call to
run the jobs.

If you're using `cron`, the following example can be added to your `crontab`::

    * * * * * /path/to/your/project/manage.py cron

You're done!  Every minute ``cron`` will check to see if you have any pending jobs
and if you do they'll be run.  No more mucking about with your ``crontab``.

If you have a more complicated setup where ``manange.py`` might not work by default
see the section below on installing ``chronograph`` in a virtual environment.


Using a Virtual Environment
---------------------------

If you're using a virtual environment, setting up ``chronograph `` involves a bit more
work, but not by much.  Included is a script called ``chronograph.sh``.  Copy this file
to your project directory.

You should open up this script and modify the path to your virtual environment's ``activate``
script::

    $PROJECT_PATH"/../../../ve/bin/activate"

Make sure that this file is executable and then update your ``crontab`` to execute the
script.  Running ``crontab -e ``::

    * * * * * /path/to/your/project/chronograph.sh /path/to/your/project

Make sure that you pass ``/path/to/your/project`` to the script as the first argument.
This will ensure that ``cron`` will not have any problems finding your project directory.


Using Chronograph
=================

If you've completed the above steps, you're all done.  Now you can add some jobs to the system.
Remember, ``chronograph`` is designed to run any install ``django-admin`` management command and
it accommodates command-line arguments as well.

Cleaning Out Old Job Logs
-------------------------

If you'd like an easy way to delete old job logs, there is a management command that will do it for
you: ``cron_clean``.  You can use it like so::

  python manage.py cron_clean [weeks|days|hours|minutes] [integer]

So, if you want to remove all jobs that are older than a week, you can do the following::

  python manage.py cron_clean weeks 1

Since this is just a simple management command, you can also easily add it to ``chronograph``, via the
admin, so that it will clear out old logs automatically.