Fault tolerant job scheduler that handles dependencies and iso8601 based schedules.

View the Project on GitHub airbnb/chronos


Chronos is airbnb's replacement for cron. It is a distributed and fault-tolerant scheduler which runs on top of mesos. It's a framework and supports custom mesos executors as well as the default command executor. Thus by default, Chronos executes SH (on most systems BASH) scripts. Chronos can be used to interact with systems such as Hadoop (incl. EMR), even if the mesos slaves on which execution happens do not have Hadoop installed. Included wrapper scripts allow transfering files and executing them on a remote machine in the background and using asynchronous callbacks to notify Chronos of job completion or failures.

Chronos has a number of advantages over regular cron. It allows you to schedule your jobs using ISO8601 repeating interval notation, which enables more flexibility in job scheduling. Chronos also supports the definition of jobs triggered by the completion of other jobs. It supports arbitrarily long dependency chains.

Quick Start

There is a file called 'installer.bash' that can be found in the bin directory of the repo. It will compile and install mesos and Chronos. After successful installation a local version of Chronos with a built-in ZK server is started. You will need Maven 3.X, a JDK and build tools to get up and running. This is how you run this installer:


If you get an error while compiling , please consult the FAQ.


The use and distribution terms for this software are covered by the Apache 2.0 License ( which can be found in the file LICENSE at the root of this distribution. By using this software in any fashion, you are agreeing to be bound by the terms of this license. You must not remove this notice, or any other, from this software.


Sample Architecture



Chronos comes with a UI which can be used to add, delete, list, modify and run jobs. It can also show a graph of job dependencies. The screenshot should give you a good idea of what Chronos can do.

Chronos UI screenshot

Chronos UI screenshot new job


You can communicate with Chronos using a RESTful JSON API over HTTP. Chronos nodes usually listen on port 4400 for API requests. All examples in this section assume that you've found a running leader at


When you have multiple Chronos nodes running, only one of them will be elected as the leader. The leader is the only node that responds to API requests, but if you attempt to talk to a non-leader your request will automatically be redirected to a leader.

Listing Jobs

A job listing returns a JSON list containing all of the jobs. Each job is a JSON hash. Interesting fields in the hashes are:

If there is a parents field there will be no schedule field and vice-versa.

Deleting a Job

Get a job name from the job listing above. Then:

Deleting All Jobs

Note: don't do this.

Manually Starting a Job

You can manually start a job by issuing an HTTP request.

Adding a Scheduled Job

The heart of job scheduling is a JSON POST request. The JSON hash you send to Chronos should contain the following fields:

Here is an example job hash:

  "schedule": "R10/2012-10-01T05:52:00Z/PT2S",
  "name": "SAMPLE_JOB1",
  "epsilon": "PT15M",
  "command": "echo 'FOO' >> /tmp/JOB1_OUT",
  "owner": "",
  "async": false

Once you've generated the hash, send it to Chronos like so:

Adding a Dependent Job

A dependent job takes the same JSON format as a scheduled job. However, instead of the schedule field, it will accept a parents field. This should be a JSON list of all jobs which must run at least once before this job will run.

Here is a more elaborate example for a dependency job hash:

    "async": true,
    "command": "bash -x /srv/data-infra/jobs/hive_query.bash run_hive hostings-earnings-summary",
    "epsilon": "PT30M",
    "errorCount": 0,
    "lastError": "",
    "lastSuccess": "2013-03-15T13:02:14.243Z",
    "name": "hostings_earnings_summary",
    "owner": "",
    "parents": [
    "retries": 2,
    "successCount": 100

Describing the Dependency Graph

Chronos allows to describe the dependency graph and has an endpoint to return this graph in form of a dotfile.

Asynchronous Jobs

If your job is long-running, you may want to run it asynchronously. In this case, you need to do two things:

1: When adding your job, add #async to the name 2: Add an executor field to your job hash and set it to /srv/mesos/utils/async-executor.arx 3: Your job when complete should report it's completion status to Chronos.

If you forget to do (2), your job will never run again because Chronos will think that it is still running. Reporting job completion to Chronos is done via another API call:

The task id is auto-generated by Chronos. It will be available in your job's environment as $mesos_task_id. Note: you may need to url-encode the mesos task id in order to submit it as part of the URL.

Obtaining Remote Executables

When specifying the command field in your job hash, use the url-runner.bash (make sure it's deployed on all slaves). Alternatively, you can also use a url in the command field, if your mesos was compiled with cURL libraries.

Debugging Chronos Jobs

Chronos itself can be configured just like dropwizard-logging via the configuration file. If there's something going wrong with the framework itself look here for information. Individual jobs log with their task id on the mesos slaves. Look in the standard out log for your job name and the string "ready for launch", or else "job ct:" and your job name. The job is done when the line in the log says:

Task with id 'value: TASK_ID **FINISHED**

To find debug logs on the mesos slave, look in /tmp/mesos/slaves on the slave instance (unless you've specifically supplied a different log folder for mesos). For example:


In that dir, the current slave run is timestamped so look for the most recent. Under that is a list of frameworks; you're interested in the Chronos framework. For example:



The curl executor is even more powerful if the specified URLs are packaged and self-contained executables. This can be done for example via arx, which bundles code into an executable archive. Arx applications in turn contain shell commands and an archive (e.g. a jar file and a startup-script). It's easy to use and there are no libraries required to unpack and execute the archive.

Signed URLs can be used to publish arx files (e.g. on s3).

To start a new scheduler you have to give the JVM access to the native mesos library. You can do so by either setting the java.library.path to the build mesos library or create an environment variable MESOS_NATIVE_LIBRARY and set it to the mesoslib.dylib / file

Also, you have to set MESOS_LAUNCHER_DIR to the src of the build of mesos such that the shell executor can be found (e.g. /Users/florian/airbnb_code/mesos/build/src).

Also set MESOS_KILLTREE to the location of the script - /Users/florian/airbnb_code/mesos/src/scripts/

If you're using the installer script this should be setup for you.


Finding a Node to Talk to

As we mentioned, Chronos is designed (not required) to run with multiple nodes of which one is elected master. If you use the cURL command line tool, you can use the "-L" flag and hit any Chronos node and you will get a 307 REDIRECT to the leader.


Chronos registers itself with at the location /airbnb/service/chronos. This value can be changed via the configuration file.