.. _changelog-2.1:
===============================
Change history for Celery 2.1
===============================
.. contents::
:local:
.. _version-2.1.4:
2.1.4
=====
:release-date: 2010-12-03 12:00 p.m. CEST
:release-by: Ask Solem
.. _v214-fixes:
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
:setting:`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).
.. _v214-documentation:
Documentation
-------------
* Adding :ref:`contributing`.
* Added :ref:`guide-optimizing`.
* Added :ref:`faq-security` section to the FAQ.
.. _version-2.1.3:
2.1.3
=====
:release-date: 2010-11-09 05:00 p.m. CEST
:release-by: Ask Solem
.. _v213-fixes:
* Fixed deadlocks in `timer2` which could lead to `djcelerymon`/`celeryev -c`
hanging.
* `EventReceiver`: now sends heartbeat request to find workers.
This means :program:`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 :class:`AsyncResult` on older Python
versions.
* worker: prefetch count was decremented by ETA tasks even if there
were no active prefetch limits.
.. _version-2.1.2:
2.1.2
=====
:release-data: TBA
.. _v212-fixes:
Fixes
-----
* worker: Now sends the :event:`task-retried` event for retried tasks.
* worker: Now honors ignore result for
:exc:`~@WorkerLostError` and timeout errors.
* ``celerybeat``: Fixed :exc:`UnboundLocalError` in ``celerybeat`` logging
when using logging setup signals.
* worker: All log messages now includes `exc_info`.
.. _version-2.1.1:
2.1.1
=====
:release-date: 2010-10-14 02:00 p.m. CEST
:release-by: Ask Solem
.. _v211-fixes:
Fixes
-----
* Now working on Windows again.
Removed dependency on the :mod:`pwd`/:mod:`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` ->
:setting:`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 :class:`float` as the expires argument
to `cache.set` is deprecated by the Memcached libraries,
so we now automatically cast to :class:`int`.
* unit tests: No longer emits logging and warnings in test output.
.. _v211-news:
News
----
* Now depends on carrot version 0.10.7.
* Added :setting:`CELERY_REDIRECT_STDOUTS`, and
:setting:`CELERYD_REDIRECT_STDOUTS_LEVEL` settings.
:setting:`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.
:setting:`CELERY_REDIRECT_STDOUTS_LEVEL` decides the log level used and is
:const:`WARNING` by default.
* Added :setting:`CELERYBEAT_SCHEDULER` setting.
This setting is used to define the default for the -S option to
:program:`celerybeat`.
Example:
.. code-block:: python
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`.
.. method:: add_consumer(queue, exchange, exchange_type, routing_key,
\*\*options)
:module:
Tells the worker to declare and consume from the specified
declaration.
.. method:: cancel_consumer(queue_name)
:module:
Tells the worker to stop consuming from queue (by queue name).
Commands also added to :program:`celeryctl` and
:class:`~celery.task.control.inspect`.
Example using ``celeryctl`` to start consuming from queue "queue", in
exchange "exchange", of type "direct" using binding key "key":
.. code-block:: console
$ celeryctl inspect add_consumer queue exchange direct key
$ celeryctl inspect cancel_consumer queue
See :ref:`monitoring-control` for more information about the
:program:`celeryctl` program.
Another example using :class:`~celery.task.control.inspect`:
.. code-block:: pycon
>>> 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`_.
.. _`Flask-Celery`: https://github.com/ask/flask-celery
.. _version-2.1.0:
2.1.0
=====
:release-date: 2010-10-08 12:00 p.m. CEST
:release-by: Ask Solem
.. _v210-important:
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.
.. _`semver`: http://semver.org
* 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.
* :pypi:`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
:mod:`platform` module.
You have to remove the old :file:`platform.py` (and maybe
:file:`platform.pyc`) file from your previous Celery installation.
To do this use :program:`python` to find the location
of this module:
.. code-block:: console
$ python
>>> import celery.platform
>>> celery.platform
<module 'celery.platform' from '/opt/devel/celery/celery/platform.pyc'>
Here the compiled module is in :file:`/opt/devel/celery/celery/`,
to remove the offending files do:
.. code-block:: console
$ rm -f /opt/devel/celery/celery/platform.py*
.. _v210-news:
News
----
* Added support for expiration of AMQP results (requires RabbitMQ 2.1.0)
The new configuration option :setting:`CELERY_AMQP_TASK_RESULT_EXPIRES`
sets the expiry time in seconds (can be int or float):
.. code-block:: python
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.
:pypi:`django-celery` now comes with a Celery monitor for the Django
Admin interface. To use this you need to run the :pypi:`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:
.. code-block:: console
$ python manage.py syncdb
2. Start the :pypi:`django-celery` snapshot camera:
.. code-block:: console
$ 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 :mod:`~celery.bin.events` available,
see :ref:`daemonizing` for more information.
New command-line arguments to ``celeryev``:
* :option:`celery events --camera`: Snapshot camera class to use.
* :option:`celery events --logfile`: Log file
* :option:`celery events --loglevel`: Log level
* :option:`celery events --maxrate`: Shutter rate limit.
* :option:`celery events --freq`: Shutter frequency
The :option:`--camera <celery events --camera>` argument is the name
of a class used to take snapshots with. It must support the interface
defined by :class:`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 :option:`--frequency <celery events --frequency>` seconds.
* :func:`~celery.task.control.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.
.. seealso::
The :ref:`monitoring-control` section in the :ref:`guide`.
Some examples:
.. code-block:: console
$ 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 (:exc:`~@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:*
.. code-block:: python
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
:option:`--loglevel <celery worker --loglevel>`/
:option:`--logfile <celery worker --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:
.. code-block:: python
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
:option:`--include <celery worker --include>`:
A comma separated list of (task) modules to be imported.
Example:
.. code-block:: console
$ celeryd -I app1.tasks,app2.tasks
* worker: now emits a warning if running as the root user (euid is 0).
* :func:`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 :state:`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:
.. code-block:: pycon
>>> 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 :data:`~celery.states.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 :state:`FAILURE` result if the
:exc:`~@WorkerLostError` exception occurs (worker process
disappeared).
* worker: Store :state:`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
:setting:`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`
-> :class:`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.
* :meth:`TaskSetResult.join <celery.result.TaskSetResult.join>`:
Added 'propagate=True' argument.
When set to :const:`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 :class:`~celery.task.base.Task` so it can be
used.
* timer2: Set `self.running=False` in
:meth:`~celery.utils.timer2.Timer.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 :mod:`celery.platforms`, so it doesn't
collide with the built-in :mod:`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 :exc:`TypeError` if kwargs argument is empty.
See issue #164.
* ``timedelta_seconds``: Use ``timedelta.total_seconds`` if running on Python 2.7
* :class:`~kombu.utils.limits.TokenBucket`: Generic Token Bucket algorithm
* :mod:`celery.events.state`: Recording of cluster state can now
be paused and resumed, including support for buffering.
.. method:: 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.
.. method:: State.thaw(replay=True)
Resumes recording of the stream.
If `replay` is true, then the recorded buffer will be applied.
.. method:: State.freeze_while(fun)
With a function to apply, freezes the stream before,
and replays the buffer after the function returns.
* :meth:`EventReceiver.capture <celery.events.EventReceiver.capture>`
Now supports a timeout keyword argument.
* worker: The mediator thread is now disabled if
:setting:`CELERY_RATE_LIMITS` is enabled, and tasks are directly sent to the
pool without going through the ready queue (*Optimization*).
.. _v210-fixes:
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 :setting:`CELERY_IGNORE_RESULT`
is enabled.
See issue #207.
* AMQP Result backend: Fixed bug with `result.get()` if
:setting:`CELERY_TRACK_STARTED` enabled.
`result.get()` would stop consuming after receiving the
:state:`STARTED` state.
* Fixed bug where new processes created by the pool supervisor becomes stuck
while reading from the task Queue.
See http://bugs.python.org/issue10037
* 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`.
.. _v210-experimental:
Experimental
------------
* multi: Added daemonization support.
multi can now be used to start, stop and restart worker nodes:
.. code-block:: console
$ celeryd-multi start jerry elaine george kramer
This also creates PID files and log files (:file:`celeryd@jerry.pid`,
..., :file:`celeryd@jerry.log`. To specify a location for these files
use the `--pidfile` and `--logfile` arguments with the `%n`
format:
.. code-block:: console
$ celeryd-multi start jerry elaine george kramer \
--logfile=/var/log/celeryd@%n.log \
--pidfile=/var/run/celeryd@%n.pid
Stopping:
.. code-block:: console
$ celeryd-multi stop jerry elaine george kramer
Restarting. The nodes will be restarted one by one as the old ones
are shutdown:
.. code-block:: console
$ celeryd-multi restart jerry elaine george kramer
Killing the nodes (**WARNING**: Will discard currently executing tasks):
.. code-block:: console
$ 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`
https://github.com/celery/celery/tree/master/extra/generic-init.d/celeryd
.. _v210-documentation:
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.