FAQ 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471
  1. ============================
  2. Frequently Asked Questions
  3. ============================
  4. Misconceptions
  5. ==============
  6. Is celery dependent on pickle?
  7. ------------------------------
  8. **Answer:** No.
  9. Celery can support any serialization scheme and has support for JSON/YAML and
  10. Pickle by default. You can even send one task using pickle, and another one
  11. with JSON seamlessly, this is because every task is associated with a
  12. content-type. The default serialization scheme is pickle because it's the most
  13. used, and it has support for sending complex objects as task arguments.
  14. You can set a global default serializer, the default serializer for a
  15. particular Task, and even what serializer to use when sending a single task
  16. instance.
  17. Is celery for Django only?
  18. --------------------------
  19. **Answer:** No.
  20. While django itself is a dependency, you can still use all of celerys features
  21. outside of a django project.
  22. Do I have to use AMQP/RabbitMQ?
  23. -------------------------------
  24. **Answer**: No.
  25. You can also use Redis or an SQL database, for instructions see:
  26. http://ask.github.com/celery/tutorials/otherqueues.html
  27. Redis or a database won't meet up to the standards
  28. of an AMQP broker. If you have strict reliability requirements you are
  29. encouraged to use RabbitMQ or another AMQP broker. Redis/database also uses
  30. pulling, so they are likely to consume more resources. However, if you for
  31. some reason is not able to use AMQP, feel free to use these alternatives.
  32. They will probably work fine for most use cases, and note that the above
  33. points are not specific to celery; If using Redis/database as a queue worked
  34. fine for you before, it probably will now. And you can always upgrade later.
  35. Is celery multi-lingual?
  36. -----------------------
  37. **Answer:** Yes.
  38. celeryd is an implementation of celery in python. If the language has an AMQP
  39. client, there shouldn't be much work to create a worker in your language.
  40. A celery worker is just a program connecting to the broker to consume
  41. messages. There's no other communication involved.
  42. Also, there's another way to be language indepedent, and that is to use REST
  43. tasks, instead of your tasks being functions, they're URLs. With this
  44. information you can even create simple web servers that enable preloading of
  45. code. For more information about REST tasks see: `Cookbook: Remote Tasks`_.
  46. .. _`Cookbook: Remote Tasks`:
  47. http://ask.github.com/celery/cookbook/remote-tasks.html
  48. Troubleshooting
  49. ===============
  50. MySQL is throwing deadlock errors, what can I do?
  51. -------------------------------------------------
  52. **Answer:** MySQL has default isolation level set to ``REPEATABLE-READ``,
  53. if you don't really need that, set it to ``READ-COMMITTED``.
  54. You can do that by adding the following to your ``my.cnf``::
  55. [mysqld]
  56. transaction-isolation = READ-COMMITTED
  57. For more information about InnoDBs transaction model see `MySQL - The InnoDB
  58. Transaction Model and Locking`_ in the MySQL user manual.
  59. (Thanks to Honza Kral and Anton Tsigularov for this solution)
  60. .. _`MySQL - The InnoDB Transaction Model and Locking`: http://dev.mysql.com/doc/refman/5.1/en/innodb-transaction-model.html
  61. celeryd is not doing anything, just hanging
  62. --------------------------------------------
  63. **Answer:** See `MySQL is throwing deadlock errors, what can I do?`_.
  64. or `Why is Task.delay/apply\* just hanging?`.
  65. Why is Task.delay/apply\*/celeryd just hanging?
  66. -----------------------------------------------
  67. **Answer:** There is a bug in some AMQP clients that will make it hang if
  68. it's not able to authenticate the current user, the password doesn't match or
  69. the user does not have access to the virtual host specified. Be sure to check
  70. your broker logs (for RabbitMQ that is ``/var/log/rabbitmq/rabbit.log`` on
  71. most systems), it usually contains a message describing the reason.
  72. Why won't celeryd run on FreeBSD?
  73. ---------------------------------
  74. **Answer:** multiprocessing.Pool requires a working POSIX semaphore
  75. implementation which isn't enabled in FreeBSD by default. You have to enable
  76. POSIX semaphores in the kernel and manually recompile multiprocessing.
  77. Luckily, Viktor Petersson has written a tutorial to get you started with
  78. Celery on FreeBSD here:
  79. http://www.playingwithwire.com/2009/10/how-to-get-celeryd-to-work-on-freebsd/
  80. I'm having ``IntegrityError: Duplicate Key`` errors. Why?
  81. ----------------------------------------------------------
  82. **Answer:** See `MySQL is throwing deadlock errors, what can I do?`_.
  83. Thanks to howsthedotcom.
  84. Why isn't my tasks processed?
  85. -----------------------------
  86. **Answer:** With RabbitMQ you can see how many consumers are currently
  87. receiving tasks by running the following command::
  88. $ rabbitmqctl list_queues -p <myvhost> name messages consumers
  89. Listing queues ...
  90. celery 2891 2
  91. This shows that there's 2891 messages waiting to be processed in the task
  92. queue, and there are two consumers processing them.
  93. One reason that the queue is never emptied could be that you have a stale
  94. celery process taking the messages hostage. This could happen if celeryd
  95. wasn't properly shut down.
  96. When a message is recieved by a worker the broker waits for it to be
  97. acknowledged before marking the message as processed. The broker will not
  98. re-send that message to another consumer until the consumer is shutdown
  99. properly.
  100. If you hit this problem you have to kill all workers manually and restart
  101. them::
  102. ps auxww | grep celeryd | awk '{print $2}' | xargs kill
  103. You might have to wait a while until all workers has finished the work they're
  104. doing, if it's still hanging after a long time you can kill them by force
  105. with::
  106. ps auxww | grep celeryd | awk '{print $2}' | xargs kill -9
  107. Why won't my Task run?
  108. ----------------------
  109. **Answer:** Did you register the task in the applications ``tasks.py`` module?
  110. (or in some other module Django loads by default, like ``models.py``?).
  111. Also there might be syntax errors preventing the tasks module being imported.
  112. You can find out if the celery daemon is able to run the task by executing the
  113. task manually:
  114. >>> from myapp.tasks import MyPeriodicTask
  115. >>> MyPeriodicTask.delay()
  116. Watch celery daemons logfile (or output if not running as a daemon), to see
  117. if it's able to find the task, or if some other error is happening.
  118. Why won't my Periodic Task run?
  119. -------------------------------
  120. **Answer:** See `Why won't my Task run?`_.
  121. How do I discard all waiting tasks?
  122. ------------------------------------
  123. **Answer:** Use ``celery.task.discard_all()``, like this:
  124. >>> from celery.task import discard_all
  125. >>> discard_all()
  126. 1753
  127. The number ``1753`` is the number of messages deleted.
  128. You can also start celeryd with the ``--discard`` argument which will
  129. accomplish the same thing.
  130. I've discarded messages, but there are still messages left in the queue?
  131. ------------------------------------------------------------------------
  132. **Answer:** Tasks are acknowledged (removed from the queue) as soon
  133. as they are actually executed. After the worker has received a task, it will
  134. take some time until it is actually executed, especially if there are a lot
  135. of tasks already waiting for execution. Messages that are not acknowledged are
  136. hold on to by the worker until it closes the connection to the broker (AMQP
  137. server). When that connection is closed (e.g because the worker was stopped)
  138. the tasks will be re-sent by the broker to the next available worker (or the
  139. same worker when it has been restarted), so to properly purge the queue of
  140. waiting tasks you have to stop all the workers, and then discard the tasks
  141. using ``discard_all``.
  142. Brokers
  143. =======
  144. Can I use celery with ActiveMQ/STOMP?
  145. -------------------------------------
  146. **Answer**: Yes. But this is somewhat experimental for now.
  147. It is certainly working ok for me in a test configuration, but it has not
  148. been tested in production like RabbitMQ. If you have any problems with
  149. using STOMP and celery, please report the bugs to the issue tracker:
  150. http://github.com/ask/celery/issues/
  151. First you have to use the ``master`` branch of ``celery``::
  152. $ git clone git://github.com/ask/celery.git
  153. $ cd celery
  154. $ sudo python setup.py install
  155. $ cd ..
  156. Then you need to install the ``stompbackend`` branch of ``carrot``::
  157. $ git clone git://github.com/ask/carrot.git
  158. $ cd carrot
  159. $ git checkout stompbackend
  160. $ sudo python setup.py install
  161. $ cd ..
  162. And my fork of ``python-stomp`` which adds non-blocking support::
  163. $ hg clone http://bitbucket.org/asksol/python-stomp/
  164. $ cd python-stomp
  165. $ sudo python setup.py install
  166. $ cd ..
  167. In this example we will use a queue called ``celery`` which we created in
  168. the ActiveMQ web admin interface.
  169. **Note**: For ActiveMQ the queue name has to have ``"/queue/"`` prepended to
  170. it. i.e. the queue ``celery`` becomes ``/queue/celery``.
  171. Since a STOMP queue is a single named entity and it doesn't have the
  172. routing capabilities of AMQP you need to set both the ``queue``, and
  173. ``exchange`` settings to your queue name. This is a minor inconvenience since
  174. carrot needs to maintain the same interface for both AMQP and STOMP (obviously
  175. the one with the most capabilities won).
  176. Use the following specific settings in your ``settings.py``:
  177. .. code-block:: python
  178. # Makes python-stomp the default backend for carrot.
  179. CARROT_BACKEND = "stomp"
  180. # STOMP hostname and port settings.
  181. AMQP_SERVER = "localhost"
  182. AMQP_PORT = 61613
  183. # The queue name to use (both queue and exchange must be set to the
  184. # same queue name when using STOMP)
  185. CELERY_AMQP_CONSUMER_QUEUE = "/queue/celery"
  186. CELERY_AMQP_EXCHANGE = "/queue/celery"
  187. Now you can go on reading the tutorial in the README, ignoring any AMQP
  188. specific options.
  189. Which features are not supported when using STOMP?
  190. --------------------------------------------------
  191. This is a (possible incomplete) list of features not available when
  192. using the STOMP backend:
  193. * routing keys
  194. * exchange types (direct, topic, headers, etc)
  195. * immediate
  196. * mandatory
  197. Features
  198. ========
  199. Can I send some tasks to only some servers?
  200. --------------------------------------------
  201. **Answer:** As of now there is only one use-case that works like this,
  202. and that is tasks of type ``A`` can be sent to servers ``x`` and ``y``,
  203. while tasks of type ``B`` can be sent to server ``z``. One server can't
  204. handle more than one routing_key, but this is coming in a later release.
  205. Say you have two servers, ``x``, and ``y`` that handles regular tasks,
  206. and one server ``z``, that only handles feed related tasks, you can use this
  207. configuration:
  208. * Servers ``x`` and ``y``: settings.py:
  209. .. code-block:: python
  210. AMQP_SERVER = "rabbit"
  211. AMQP_PORT = 5678
  212. AMQP_USER = "myapp"
  213. AMQP_PASSWORD = "secret"
  214. AMQP_VHOST = "myapp"
  215. CELERY_AMQP_CONSUMER_QUEUE = "regular_tasks"
  216. CELERY_AMQP_EXCHANGE = "tasks"
  217. CELERY_AMQP_PUBLISHER_ROUTING_KEY = "task.regular"
  218. CELERY_AMQP_CONSUMER_ROUTING_KEY = "task.#"
  219. CELERY_AMQP_EXCHANGE_TYPE = "topic"
  220. * Server ``z``: settings.py:
  221. .. code-block:: python
  222. AMQP_SERVER = "rabbit"
  223. AMQP_PORT = 5678
  224. AMQP_USER = "myapp"
  225. AMQP_PASSWORD = "secret"
  226. AMQP_VHOST = "myapp"
  227. CELERY_AMQP_EXCHANGE = "tasks"
  228. CELERY_AMQP_PUBLISHER_ROUTING_KEY = "task.regular"
  229. CELERY_AMQP_EXCHANGE_TYPE = "topic"
  230. # This is the settings different for this server:
  231. CELERY_AMQP_CONSUMER_QUEUE = "feed_tasks"
  232. CELERY_AMQP_CONSUMER_ROUTING_KEY = "feed.#"
  233. Now to make a Task run on the ``z`` server you need to set its
  234. ``routing_key`` attribute so it starts with the words ``"task.feed."``:
  235. .. code-block:: python
  236. from feedaggregator.models import Feed
  237. from celery.task import Task
  238. class FeedImportTask(Task):
  239. routing_key = "feed.importer"
  240. def run(self, feed_url):
  241. # something importing the feed
  242. Feed.objects.import_feed(feed_url)
  243. You can also override this using the ``routing_key`` argument to
  244. :func:`celery.task.apply_async`:
  245. >>> from celery.task import apply_async
  246. >>> from myapp.tasks import RefreshFeedTask
  247. >>> apply_async(RefreshFeedTask, args=["http://cnn.com/rss"],
  248. ... routing_key="feed.importer")
  249. Can I use celery without Django?
  250. --------------------------------
  251. **Answer:** Yes.
  252. Celery uses something called loaders to read/setup configuration, import
  253. modules that registers tasks and to decide what happens when a task is
  254. executed. Currently there are two loaders, the default loader and the Django
  255. loader. If you want to use celery without a Django project, you either have to
  256. use the default loader, or write a loader of your own.
  257. The rest of this answer describes how to use the default loader.
  258. First of all, installation. You need to get the development version of
  259. celery from github::
  260. $ git clone git://github.com/ask/celery.git
  261. $ cd celery
  262. # python setup.py install # as root
  263. While it is possible to use celery from outside of Django, we still need
  264. Django itself to run, this is to use the ORM and cache-framework, etc.
  265. Duplicating these features would be time consuming and mostly pointless, so
  266. we decided that having a dependency on Django itself was a good thing.
  267. Install Django using your favorite install tool, ``easy_install``, ``pip``, or
  268. whatever::
  269. # easy_install django # as root
  270. You need a configuration file named ``celeryconfig.py``, either in the
  271. directory you run ``celeryd`` in, or in a Python library path where it is
  272. able to find it. The configuration file can contain any of the settings
  273. described in :mod:`celery.conf`, and in additional if you're using the
  274. database backend you have to configure the database. Here is an example
  275. configuration using the database backend with MySQL:
  276. .. code-block:: python
  277. # Broker configuration
  278. AMQP_SERVER = "localhost"
  279. AMQP_PORT = "5672"
  280. AMQP_VHOST = "celery"
  281. AMQP_USER = "celery"
  282. AMQP_PASSWORD = "celerysecret"
  283. CARROT_BACKEND="amqp"
  284. # Using the database backend.
  285. CELERY_BACKEND = "database"
  286. DATABASE_ENGINE = "mysql" # see Django docs for a description of these.
  287. DATABASE_NAME = "mydb"
  288. DATABASE_HOST = "mydb.example.org"
  289. DATABASE_USER = "myuser"
  290. DATABASE_PASSWORD = "mysecret"
  291. # Number of processes that processes tasks simultaneously.
  292. CELERYD_CONCURRENCY = 8
  293. # Modules to import when celeryd starts.
  294. # This must import every module where you register tasks so celeryd
  295. # is able to find and run them.
  296. CELERY_IMPORTS = ("mytaskmodule1", "mytaskmodule2")
  297. Now with this configuration file in the current directory you have to
  298. run ``celeryinit`` to create the database tables::
  299. $ celeryinit
  300. Then you should be able to successfully run ``celeryd``::
  301. $ celeryd --loglevel=INFO
  302. and send a task from a python shell (note that it must be able to import
  303. ``celeryconfig.py``):
  304. >>> from celery.task.builtins import PingTask
  305. >>> result = PingTask.apply_async()
  306. >>> result.get()
  307. 'pong'
  308. The celery test-suite is failing
  309. --------------------------------
  310. **Answer**: You're running tests from your own Django applicaiton, and celerys
  311. tests are failing and celerys tests are failing in that context?
  312. If so, read on for a trick, if not please report the test failure to our issue
  313. tracker at GitHub.
  314. http://github.com/ask/celery/issues/
  315. That Django is running tests for all applications in ``INSTALLED_APPS``
  316. is a pet peeve of mine. You should use a test runner that either
  317. 1) Explicitly lists the apps you want to run tests for, or
  318. 2) make a test runner that skips tests for apps you don't want to run.
  319. For example this test runner that celery is using:
  320. http://bit.ly/NVKep
  321. To use this add the following to your settings.py:
  322. .. code-block:: python
  323. TEST_RUNNER = "celery.tests.runners.run_tests"
  324. TEST_APPS = (
  325. "app1",
  326. "app2",
  327. "app3",
  328. "app4",
  329. )
  330. If you just want to skip celery you could use:
  331. .. code-block:: python
  332. INSTALLED_APPS = (.....)
  333. TEST_RUNNER = "celery.tests.runners.run_tests"
  334. TEST_APPS = filter(lambda k: k != "celery", INSTALLED_APPS)