This document describes the current stable version of Celery (5.2). For development docs, go here.

Change history for Celery 2.1

2.1.4

release-date:

2010-12-03 12:00 p.m. CEST

release-by:

Ask Solem

Fixes

  • Execution options to apply_async now takes precedence over options returned by active routers. This was a regression introduced recently (Issue #244).

  • curses monitor: Long arguments are now truncated so curses doesn’t crash with out of bounds errors (Issue #235).

  • multi: Channel errors occurring while handling control commands no longer crash the worker but are instead logged with severity error.

  • SQLAlchemy database backend: Fixed a race condition occurring when the client wrote the pending state. Just like the Django database backend, it does no longer save the pending state (Issue #261 + Issue #262).

  • Error email body now uses repr(exception) instead of str(exception), as the latter could result in Unicode decode errors (Issue #245).

  • Error email timeout value is now configurable by using the EMAIL_TIMEOUT setting.

  • celeryev: Now works on Windows (but the curses monitor won’t work without having curses).

  • Unit test output no longer emits non-standard characters.

  • worker: The broadcast consumer is now closed if the connection is reset.

  • worker: Now properly handles errors occurring while trying to acknowledge the message.

  • TaskRequest.on_failure now encodes traceback using the current file-system

    encoding (Issue #286).

  • EagerResult can now be pickled (Issue #288).

Documentation

2.1.3

release-date:

2010-11-09 05:00 p.m. CEST

release-by:

Ask Solem

  • Fixed deadlocks in timer2 which could lead to djcelerymon/celeryev -c hanging.

  • EventReceiver: now sends heartbeat request to find workers.

    This means celeryev and friends finds workers immediately at start-up.

  • celeryev curses monitor: Set screen_delay to 10ms, so the screen refreshes more often.

  • Fixed pickling errors when pickling AsyncResult on older Python versions.

  • worker: prefetch count was decremented by ETA tasks even if there were no active prefetch limits.

2.1.2

release-data:

TBA

Fixes

  • worker: Now sends the task-retried event for retried tasks.

  • worker: Now honors ignore result for WorkerLostError and timeout errors.

  • celerybeat: Fixed UnboundLocalError in celerybeat logging when using logging setup signals.

  • worker: All log messages now includes exc_info.

2.1.1

release-date:

2010-10-14 02:00 p.m. CEST

release-by:

Ask Solem

Fixes

  • Now working on Windows again.

    Removed dependency on the pwd/grp modules.

  • snapshots: Fixed race condition leading to loss of events.

  • worker: Reject tasks with an ETA that cannot be converted to a time stamp.

    See issue #209

  • concurrency.processes.pool: The semaphore was released twice for each task (both at ACK and result ready).

    This has been fixed, and it is now released only once per task.

  • docs/configuration: Fixed typo CELERYD_TASK_SOFT_TIME_LIMIT -> CELERYD_TASK_SOFT_TIME_LIMIT.

    See issue #214

  • control command dump_scheduled: was using old .info attribute

  • multi: Fixed set changed size during iteration bug

    occurring in the restart command.

  • worker: Accidentally tried to use additional command-line arguments.

    This would lead to an error like:

    got multiple values for keyword argument ‘concurrency’.

    Additional command-line arguments are now ignored, and doesn’t produce this error. However – we do reserve the right to use positional arguments in the future, so please don’t depend on this behavior.

  • celerybeat: Now respects routers and task execution options again.

  • celerybeat: Now reuses the publisher instead of the connection.

  • Cache result backend: Using float as the expires argument to cache.set is deprecated by the Memcached libraries, so we now automatically cast to int.

  • unit tests: No longer emits logging and warnings in test output.

News

  • Now depends on carrot version 0.10.7.

  • Added CELERY_REDIRECT_STDOUTS, and CELERYD_REDIRECT_STDOUTS_LEVEL settings.

    CELERY_REDIRECT_STDOUTS is used by the worker and beat. All output to stdout and stderr will be redirected to the current logger if enabled.

    CELERY_REDIRECT_STDOUTS_LEVEL decides the log level used and is WARNING by default.

  • Added CELERYBEAT_SCHEDULER setting.

    This setting is used to define the default for the -S option to celerybeat.

    Example:

    CELERYBEAT_SCHEDULER = 'djcelery.schedulers.DatabaseScheduler'

  • Added Task.expires: Used to set default expiry time for tasks.

  • New remote control commands: add_consumer and cancel_consumer.

    add_consumer(queue, exchange, exchange_type, routing_key,
    \*\*options)

    Tells the worker to declare and consume from the specified declaration.

    cancel_consumer(queue_name)

    Tells the worker to stop consuming from queue (by queue name).

    Commands also added to celeryctl and inspect.

    Example using celeryctl to start consuming from queue “queue”, in exchange “exchange”, of type “direct” using binding key “key”:

    $ celeryctl inspect add_consumer queue exchange direct key
$ celeryctl inspect cancel_consumer queue

    See Management Command-line Utilities (inspect/control) for more information about the celeryctl program.

    Another example using inspect:

    >>> from celery.task.control import inspect
>>> inspect.add_consumer(queue='queue', exchange='exchange',
...                      exchange_type='direct',
...                      routing_key='key',
...                      durable=False,
...                      auto_delete=True)

>>> inspect.cancel_consumer('queue')

  • celerybeat: Now logs the traceback if a message can’t be sent.

  • celerybeat: Now enables a default socket timeout of 30 seconds.

  • README/introduction/homepage: Added link to Flask-Celery.

2.1.0

release-date:

2010-10-08 12:00 p.m. CEST

release-by:

Ask Solem

Important Notes

  • Celery is now following the versioning semantics defined by semver.

    This means we’re no longer allowed to use odd/even versioning semantics By our previous versioning scheme this stable release should’ve been version 2.2.

  • Now depends on Carrot 0.10.7.

  • No longer depends on SQLAlchemy, this needs to be installed separately if the database result backend is used.

  • django-celery now comes with a monitor for the Django Admin interface. This can also be used if you’re not a Django user. (Update: Django-Admin monitor has been replaced with Flower, see the Monitoring guide).

  • If you get an error after upgrading saying: AttributeError: ‘module’ object has no attribute ‘system’,

    Then this is because the celery.platform module has been renamed to celery.platforms to not collide with the built-in platform module.

    You have to remove the old platform.py (and maybe platform.pyc) file from your previous Celery installation.

    To do this use python to find the location of this module:

    $ python
>>> import celery.platform
>>> celery.platform
<module 'celery.platform' from '/opt/devel/celery/celery/platform.pyc'>

    Here the compiled module is in /opt/devel/celery/celery/, to remove the offending files do:

    $ rm -f /opt/devel/celery/celery/platform.py*

News

  • Added support for expiration of AMQP results (requires RabbitMQ 2.1.0)

    The new configuration option CELERY_AMQP_TASK_RESULT_EXPIRES sets the expiry time in seconds (can be int or float):

    CELERY_AMQP_TASK_RESULT_EXPIRES = 30 * 60  # 30 minutes.
CELERY_AMQP_TASK_RESULT_EXPIRES = 0.80     # 800 ms.

  • celeryev: Event Snapshots

    If enabled, the worker sends messages about what the worker is doing. These messages are called “events”. The events are used by real-time monitors to show what the cluster is doing, but they’re not very useful for monitoring over a longer period of time. Snapshots lets you take “pictures” of the clusters state at regular intervals. This can then be stored in a database to generate statistics with, or even monitoring over longer time periods.

    django-celery now comes with a Celery monitor for the Django Admin interface. To use this you need to run the django-celery snapshot camera, which stores snapshots to the database at configurable intervals.

    To use the Django admin monitor you need to do the following:

    1. Create the new database tables:

      $ python manage.py syncdb

    2. Start the django-celery snapshot camera:

      $ python manage.py celerycam

    3. Open up the django admin to monitor your cluster.

    The admin interface shows tasks, worker nodes, and even lets you perform some actions, like revoking and rate limiting tasks, and shutting down worker nodes.

    There’s also a Debian init.d script for events available, see Daemonization for more information.

    New command-line arguments to celeryev:

    The --camera argument is the name of a class used to take snapshots with. It must support the interface defined by celery.events.snapshot.Polaroid.

    Shutter frequency controls how often the camera thread wakes up, while the rate limit controls how often it will actually take a snapshot. The rate limit can be an integer (snapshots/s), or a rate limit string which has the same syntax as the task rate limit strings (“200/m”, “10/s”, “1/h”, etc).

    For the Django camera case, this rate limit can be used to control how often the snapshots are written to the database, and the frequency used to control how often the thread wakes up to check if there’s anything new.

    The rate limit is off by default, which means it will take a snapshot for every --frequency seconds.

  • broadcast(): Added callback argument, this can be used to process replies immediately as they arrive.

  • celeryctl: New command line utility to manage and inspect worker nodes, apply tasks and inspect the results of tasks.

    See also

    The Management Command-line Utilities (inspect/control) section in the User Guide.

    Some examples:

    $ celeryctl apply tasks.add -a '[2, 2]' --countdown=10

$ celeryctl inspect active
$ celeryctl inspect registered_tasks
$ celeryctl inspect scheduled
$ celeryctl inspect --help
$ celeryctl apply --help

  • Added the ability to set an expiry date and time for tasks.

    Example:

    >>> # Task expires after one minute from now.
>>> task.apply_async(args, kwargs, expires=60)
>>> # Also supports datetime
>>> task.apply_async(args, kwargs,
...                  expires=datetime.now() + timedelta(days=1)

    When a worker receives a task that’s been expired it will be marked as revoked (TaskRevokedError).

  • Changed the way logging is configured.

    We now configure the root logger instead of only configuring our custom logger. In addition we don’t hijack the multiprocessing logger anymore, but instead use a custom logger name for different applications:

    Application

    Logger Name

    celeryd

    "celery"

    celerybeat

    "celery.beat"

    celeryev

    "celery.ev"

    This means that the loglevel and logfile arguments will affect all registered loggers (even those from third-party libraries). Unless you configure the loggers manually as shown below, that is.

    Users can choose to configure logging by subscribing to the :signal:`~celery.signals.setup_logging` signal:

    from logging.config import fileConfig
from celery import signals

@signals.setup_logging.connect
def setup_logging(**kwargs):
    fileConfig('logging.conf')

    If there are no receivers for this signal, the logging subsystem will be configured using the --loglevel/ --logfile arguments, this will be used for all defined loggers.

    Remember that the worker also redirects stdout and stderr to the Celery logger, if manually configure logging you also need to redirect the standard outs manually:

     from logging.config import fileConfig
 from celery import log

def setup_logging(**kwargs):
     import logging
     fileConfig('logging.conf')
     stdouts = logging.getLogger('mystdoutslogger')
     log.redirect_stdouts_to_logger(stdouts, loglevel=logging.WARNING)

  • worker Added command line option --include:

    A comma separated list of (task) modules to be imported.

    Example:

    $ celeryd -I app1.tasks,app2.tasks

  • worker: now emits a warning if running as the root user (euid is 0).

  • celery.messaging.establish_connection(): Ability to override defaults used using keyword argument “defaults”.

  • worker: Now uses multiprocessing.freeze_support() so that it should work with py2exe, PyInstaller, cx_Freeze, etc.

  • worker: Now includes more meta-data for the STARTED state: PID and host name of the worker that started the task.

    See issue #181

  • subtask: Merge additional keyword arguments to subtask() into task keyword arguments.

    For example:

    >>> s = subtask((1, 2), {'foo': 'bar'}, baz=1)
>>> s.args
(1, 2)
>>> s.kwargs
{'foo': 'bar', 'baz': 1}

    See issue #182.

  • worker: Now emits a warning if there’s already a worker node using the same name running on the same virtual host.

  • AMQP result backend: Sending of results are now retried if the connection is down.

  • AMQP result backend: result.get(): Wait for next state if state isn’t

    in READY_STATES.

  • TaskSetResult now supports subscription.

    >>> res = TaskSet(tasks).apply_async()
>>> res[0].get()

  • Added Task.send_error_emails + Task.error_whitelist, so these can be configured per task instead of just by the global setting.

  • Added Task.store_errors_even_if_ignored, so it can be changed per Task, not just by the global setting.

  • The Crontab scheduler no longer wakes up every second, but implements remaining_estimate (Optimization).

  • worker: Store FAILURE result if the

    WorkerLostError exception occurs (worker process disappeared).

  • worker: Store FAILURE result if one of the *TimeLimitExceeded exceptions occurs.

  • Refactored the periodic task responsible for cleaning up results.

    • The backend cleanup task is now only added to the schedule if

      CELERY_TASK_RESULT_EXPIRES is set.

    • If the schedule already contains a periodic task named “celery.backend_cleanup” it won’t change it, so the behavior of the backend cleanup task can be easily changed.

    • The task is now run every day at 4:00 AM, rather than every day since the first time it was run (using Crontab schedule instead of run_every)

    • Renamed celery.task.builtins.DeleteExpiredTaskMetaTask

      -> celery.task.builtins.backend_cleanup

    • The task itself has been renamed from “celery.delete_expired_task_meta” to “celery.backend_cleanup”

    See issue #134.

  • Implemented AsyncResult.forget for SQLAlchemy/Memcached/Redis/Tokyo Tyrant backends (forget and remove task result).

    See issue #184.

  • TaskSetResult.join: Added ‘propagate=True’ argument.

    When set to False exceptions occurring in subtasks will not be re-raised.

  • Added Task.update_state(task_id, state, meta) as a shortcut to task.backend.store_result(task_id, meta, state).

    The backend interface is “private” and the terminology outdated, so better to move this to Task so it can be used.

  • timer2: Set self.running=False in stop() so it won’t try to join again on subsequent calls to stop().

  • Log colors are now disabled by default on Windows.

  • celery.platform renamed to celery.platforms, so it doesn’t collide with the built-in platform module.

  • Exceptions occurring in Mediator+Pool callbacks are now caught and logged instead of taking down the worker.

  • Redis result backend: Now supports result expiration using the Redis EXPIRE command.

  • unit tests: Don’t leave threads running at tear down.

  • worker: Task results shown in logs are now truncated to 46 chars.

  • Task.__name__ is now an alias to self.__class__.__name__.

    This way tasks introspects more like regular functions.

  • Task.retry: Now raises TypeError if kwargs argument is empty.

    See issue #164.

  • timedelta_seconds: Use timedelta.total_seconds if running on Python 2.7

  • TokenBucket: Generic Token Bucket algorithm

  • celery.events.state: Recording of cluster state can now be paused and resumed, including support for buffering.

    State.freeze(buffer=True)

    Pauses recording of the stream.

    If buffer is true, events received while being frozen will be buffered, and may be replayed later.

    State.thaw(replay=True)

    Resumes recording of the stream.

    If replay is true, then the recorded buffer will be applied.

    State.freeze_while(fun)

    With a function to apply, freezes the stream before, and replays the buffer after the function returns.

  • EventReceiver.capture Now supports a timeout keyword argument.

  • worker: The mediator thread is now disabled if CELERY_RATE_LIMITS is enabled, and tasks are directly sent to the pool without going through the ready queue (Optimization).

Fixes

  • Pool: Process timed out by TimeoutHandler must be joined by the Supervisor, so don’t remove it from the internal process list.

    See issue #192.

  • TaskPublisher.delay_task now supports exchange argument, so exchange can be overridden when sending tasks in bulk using the same publisher

    See issue #187.

  • the worker no longer marks tasks as revoked if CELERY_IGNORE_RESULT is enabled.

    See issue #207.

  • AMQP Result backend: Fixed bug with result.get() if CELERY_TRACK_STARTED enabled.

    result.get() would stop consuming after receiving the STARTED state.

  • Fixed bug where new processes created by the pool supervisor becomes stuck while reading from the task Queue.

  • Fixed timing issue when declaring the remote control command reply queue

    This issue could result in replies being lost, but have now been fixed.

  • Backward compatible LoggerAdapter implementation: Now works for Python 2.4.

    Also added support for several new methods: fatal, makeRecord, _log, log, isEnabledFor, addHandler, removeHandler.

Experimental

  • multi: Added daemonization support.

    multi can now be used to start, stop and restart worker nodes:

    $ celeryd-multi start jerry elaine george kramer

    This also creates PID files and log files (celeryd@jerry.pid, …, celeryd@jerry.log. To specify a location for these files use the –pidfile and –logfile arguments with the %n format:

    $ celeryd-multi start jerry elaine george kramer \
                --logfile=/var/log/celeryd@%n.log \
                --pidfile=/var/run/celeryd@%n.pid

    Stopping:

    $ celeryd-multi stop jerry elaine george kramer

    Restarting. The nodes will be restarted one by one as the old ones are shutdown:

    $ celeryd-multi restart jerry elaine george kramer

    Killing the nodes (WARNING: Will discard currently executing tasks):

    $ celeryd-multi kill jerry elaine george kramer

    See celeryd-multi help for help.

  • multi: start command renamed to show.

    celeryd-multi start will now actually start and detach worker nodes. To just generate the commands you have to use celeryd-multi show.

  • worker: Added –pidfile argument.

    The worker will write its pid when it starts. The worker will not be started if this file exists and the pid contained is still alive.

  • Added generic init.d script using celeryd-multi

Documentation

  • Added User guide section: Monitoring

  • Added user guide section: Periodic Tasks

    Moved from getting-started/periodic-tasks and updated.

  • tutorials/external moved to new section: “community”.

  • References has been added to all sections in the documentation.

    This makes it easier to link between documents.