Background jobs with php and resque: part 7, Manage workers with Fresque

Fresque is a command line tool to manage your php-resque workers

Fresque removes all the hassles of manipulating process, pipe, daemon and other cli-guru related commands when managing php resque workers.

Instead of starting a worker with this command:

QUEUE=notification php resque.php

You use:

fresque start --queue notification

You begin to see its real usefulness when it convert that command

nohup QUEUE=notification php resque.php >> /path/to/your/logfile.log 2>&1 &

into that:

fresque start --queue notification --log /path/to/your/logfile.log

Fresque comes with a default fresque.ini file, storing the queues default settings. You can then transform the above command into:

fresque start

Cool, isn’t it ?

Prerequisites

A working php-resque installation, and an understanding of the workers starting and stopping process.

Installation

Download

Clone the github repository

git clone git://github.com/kamisama/Fresque.git

Or download the latest release directly, and uncompress it. Folder should be renamed to Fresque.

Installation

Navigate into the Resque folder, and install all the dependencies with Composer

cd the/fresque/folder/you/just/cloned--or-downloaded
curl -s https://getcomposer.org/installer | php
php composer.phar install

Install as a composer dependency

If you application is already using Composer, just add fresque as a dependency in your composer.json:

"require": {
    .. your dependencies ...
    "fresque/fresque": ">=1.0.0"
},

Configuration

See the fresque.ini file located inside the Fresque directory. There is an inline documentation that will explain each settings in details.

Usage

You can add the fresque executable ( Fresque/fresque) to your system path. You’ll then be able to use it anywhere, like that:

fresque COMMAND

Else, you’ll have to use

/path/to/Fresque/fresque COMMAND
# Or
cd /path/to/Fresque
./fresque COMMAND

Let’s see the available COMMAND:

  • start

To start a new resque worker. By default, it will use the default configuration defined in you fresque.ini for the queue name, the pooling frequency, and other various options. You can override all of them with an option flag. Available options :

-u or --user : User running the php process. Should be the user running your php application, usually www-data for apache. Using a different user could lead to permissions problems.

-q or --queue : A list of queues name, separated with a comma.

-i or --interval : Polling frequency. Number of seconds between each polling.

-n or --workers : Number of workers working on the same queue.

-l or --log : Absolute path to the log file. You can set a different log for each worker. The --user must have permission to read and write to that file (and the parent folder, since the file will be created if non-existent).

For creating multiple queues with different options, just run start again.

  • stop

To shutdown worker. Will wait for all jobs to finish, then shutdown the worker. If more than one worker is running, you’ll have to choose the worker to stop from a list of workers.

-f or --force : Force shutdown, without waiting for the jobs to finish. All jobs currently processing will fail.

-w or --all : Stop all workers, skipping the worker list menu.

  • restart

To restart all the workers, keeping their settings.

  • load

To start a batch of pre-defined workers (set in your configuration file). See fresque.ini for more informations.

  • stats

Display total number of failed/processed jobs, as well as various stats for each workers.

  • tail

Tail the workers’ logs. If you have more than one log file, you’ll have to choose the log to tail from a log file menu.

  • enqueue

Add a job to a queue. Takes 3 arguments :

queuename : Name of the queue you will enqueue this job to

jobclass : Name of the class that will perform the job, and that your application autoloader will have to load.

arguments : comma separated list of arguments, passed to the job.

Will print the Job ID if the job is successfully enqueued.

Successfully enqueuing a job does not means it will perform it successfully
  • test

Test your configuration. If no options are provided, it will test the fresque.ini. It accepts all options, to let you test them.

Finally, there’s some global options, that can be used for all commands. Default value in your config file will be used unless you use these.

-s or --host : Redis hostname

-p or --port : Redis port

-b or --lib : Absolute path to the php-resque library. Used when you already have your own, and don’t want to use the one shipped with fresque.

-c or --config : Absolute path to your config file. You can use different config for different workers. Default one is fresque.ini, in the same directory as the executable.

-a or --autoloader : Absolute path to your application entry point. Usually, it should be the file that will load all your job classes.

As Fresque is still evolving, some commands or flags could have been changed. Refer to Fresque documentation for up-to-date commands list.

Examples

See the official documentation for examples. If you’re already familiar with CakeResque, this tool share the same API, all commands should be the same.