configuration.rst 45 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826
  1. .. _configuration:
  2. ============================
  3. Configuration and defaults
  4. ============================
  5. This document describes the configuration options available.
  6. If you're using the default loader, you must create the :file:`celeryconfig.py`
  7. module and make sure it is available on the Python path.
  8. .. contents::
  9. :local:
  10. :depth: 2
  11. .. _conf-example:
  12. Example configuration file
  13. ==========================
  14. This is an example configuration file to get you started.
  15. It should contain all you need to run a basic Celery set-up.
  16. .. code-block:: python
  17. ## Broker settings.
  18. BROKER_URL = "amqp://guest:guest@localhost:5672//"
  19. # List of modules to import when celery starts.
  20. CELERY_IMPORTS = ("myapp.tasks", )
  21. ## Using the database to store task state and results.
  22. CELERY_RESULT_BACKEND = "database"
  23. CELERY_RESULT_DBURI = "sqlite:///mydatabase.db"
  24. CELERY_ANNOTATIONS = {"tasks.add": {"rate_limit": "10/s"}}
  25. Configuration Directives
  26. ========================
  27. .. _conf-datetime:
  28. Time and date settings
  29. ----------------------
  30. .. setting:: CELERY_ENABLE_UTC
  31. CELERY_ENABLE_UTC
  32. ~~~~~~~~~~~~~~~~~
  33. .. versionadded:: 2.5
  34. If enabled dates and times in messages will be converted to use
  35. the UTC timezone.
  36. Note that workers running Celery versions below 2.5 will assume a local
  37. timezone for all messages, so only enable if all workers have been
  38. upgraded.
  39. Enabled by default since version 3.0.
  40. .. setting:: CELERY_TIMEZONE
  41. CELERY_TIMEZONE
  42. ~~~~~~~~~~~~~~~
  43. Configure Celery to use a custom time zone.
  44. The timezone value can be any time zone supported by the `pytz`_
  45. library.
  46. If not set the UTC timezone is used. For backwards compatibility
  47. there is also a :setting:`CELERY_ENABLE_UTC` setting, and this is set
  48. to false the system local timezone is used instead.
  49. .. _`pytz`: http://pypi.python.org/pypi/pytz/
  50. .. _conf-tasks:
  51. Task settings
  52. -------------
  53. .. setting:: CELERY_ANNOTATIONS
  54. CELERY_ANNOTATIONS
  55. ~~~~~~~~~~~~~~~~~~
  56. This setting can be used to rewrite any task attribute from the
  57. configuration. The setting can be a dict, or a list of annotation
  58. objects that filter for tasks and return a map of attributes
  59. to change.
  60. This will change the ``rate_limit`` attribute for the ``tasks.add``
  61. task:
  62. .. code-block:: python
  63. CELERY_ANNOTATIONS = {"tasks.add": {"rate_limit": "10/s"}}
  64. or change the same for all tasks:
  65. .. code-block:: python
  66. CELERY_ANNOTATIONS = {"*": {"rate_limit": "10/s"}}
  67. You can change methods too, for example the ``on_failure`` handler:
  68. .. code-block:: python
  69. def my_on_failure(self, exc, task_id, args, kwargs, einfo):
  70. print("Oh no! Task failed: {0!r}".format(exc))
  71. CELERY_ANNOTATIONS = {"*": {"on_failure": my_on_failure}}
  72. If you need more flexibility then you can use objects
  73. instead of a dict to choose which tasks to annotate:
  74. .. code-block:: python
  75. class MyAnnotate(object):
  76. def annotate(self, task):
  77. if task.name.startswith("tasks."):
  78. return {"rate_limit": "10/s"}
  79. CELERY_ANNOTATIONS = (MyAnnotate(), {...})
  80. .. _conf-concurrency:
  81. Concurrency settings
  82. --------------------
  83. .. setting:: CELERYD_CONCURRENCY
  84. CELERYD_CONCURRENCY
  85. ~~~~~~~~~~~~~~~~~~~
  86. The number of concurrent worker processes/threads/green threads executing
  87. tasks.
  88. If you're doing mostly I/O you can have more processes,
  89. but if mostly CPU-bound, try to keep it close to the
  90. number of CPUs on your machine. If not set, the number of CPUs/cores
  91. on the host will be used.
  92. Defaults to the number of available CPUs.
  93. .. setting:: CELERYD_PREFETCH_MULTIPLIER
  94. CELERYD_PREFETCH_MULTIPLIER
  95. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  96. How many messages to prefetch at a time multiplied by the number of
  97. concurrent processes. The default is 4 (four messages for each
  98. process). The default setting is usually a good choice, however -- if you
  99. have very long running tasks waiting in the queue and you have to start the
  100. workers, note that the first worker to start will receive four times the
  101. number of messages initially. Thus the tasks may not be fairly distributed
  102. to the workers.
  103. .. note::
  104. Tasks with ETA/countdown are not affected by prefetch limits.
  105. .. _conf-result-backend:
  106. Task result backend settings
  107. ----------------------------
  108. .. setting:: CELERY_RESULT_BACKEND
  109. CELERY_RESULT_BACKEND
  110. ~~~~~~~~~~~~~~~~~~~~~
  111. :Deprecated aliases: ``CELERY_BACKEND``
  112. The backend used to store task results (tombstones).
  113. Disabled by default.
  114. Can be one of the following:
  115. * database
  116. Use a relational database supported by `SQLAlchemy`_.
  117. See :ref:`conf-database-result-backend`.
  118. * cache
  119. Use `memcached`_ to store the results.
  120. See :ref:`conf-cache-result-backend`.
  121. * mongodb
  122. Use `MongoDB`_ to store the results.
  123. See :ref:`conf-mongodb-result-backend`.
  124. * redis
  125. Use `Redis`_ to store the results.
  126. See :ref:`conf-redis-result-backend`.
  127. * amqp
  128. Send results back as AMQP messages
  129. See :ref:`conf-amqp-result-backend`.
  130. * cassandra
  131. Use `Cassandra`_ to store the results.
  132. See :ref:`conf-cassandra-result-backend`.
  133. * ironcache
  134. Use `IronCache`_ to store the results.
  135. See :ref:`conf-ironcache-result-backend`.
  136. * couchbase
  137. Use `Couchbase`_ to store the results.
  138. See :ref:`conf-couchbase-result-backend`.
  139. .. warning:
  140. While the AMQP result backend is very efficient, you must make sure
  141. you only receive the same result once. See :doc:`userguide/calling`).
  142. .. _`SQLAlchemy`: http://sqlalchemy.org
  143. .. _`memcached`: http://memcached.org
  144. .. _`MongoDB`: http://mongodb.org
  145. .. _`Redis`: http://redis.io
  146. .. _`Cassandra`: http://cassandra.apache.org/
  147. .. _`IronCache`: http://www.iron.io/cache
  148. .. _`Couchbase`: http://www.couchbase.com/
  149. .. setting:: CELERY_RESULT_SERIALIZER
  150. CELERY_RESULT_SERIALIZER
  151. ~~~~~~~~~~~~~~~~~~~~~~~~
  152. Result serialization format. Default is `"pickle"`. See
  153. :ref:`calling-serializers` for information about supported
  154. serialization formats.
  155. .. _conf-database-result-backend:
  156. Database backend settings
  157. -------------------------
  158. .. setting:: CELERY_RESULT_DBURI
  159. CELERY_RESULT_DBURI
  160. ~~~~~~~~~~~~~~~~~~~
  161. Please see `Supported Databases`_ for a table of supported databases.
  162. To use this backend you need to configure it with an
  163. `Connection String`_, some examples include:
  164. .. code-block:: python
  165. # sqlite (filename)
  166. CELERY_RESULT_DBURI = "sqlite:///celerydb.sqlite"
  167. # mysql
  168. CELERY_RESULT_DBURI = "mysql://scott:tiger@localhost/foo"
  169. # postgresql
  170. CELERY_RESULT_DBURI = "postgresql://scott:tiger@localhost/mydatabase"
  171. # oracle
  172. CELERY_RESULT_DBURI = "oracle://scott:tiger@127.0.0.1:1521/sidname"
  173. See `Connection String`_ for more information about connection
  174. strings.
  175. .. _`Supported Databases`:
  176. http://www.sqlalchemy.org/docs/core/engines.html#supported-databases
  177. .. _`Connection String`:
  178. http://www.sqlalchemy.org/docs/core/engines.html#database-urls
  179. .. setting:: CELERY_RESULT_ENGINE_OPTIONS
  180. CELERY_RESULT_ENGINE_OPTIONS
  181. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  182. To specify additional SQLAlchemy database engine options you can use
  183. the :setting:`CELERY_RESULT_ENGINE_OPTIONS` setting::
  184. # echo enables verbose logging from SQLAlchemy.
  185. CELERY_RESULT_ENGINE_OPTIONS = {"echo": True}
  186. .. setting:: CELERY_RESULT_DB_SHORT_LIVED_SESSIONS
  187. CELERY_RESULT_DB_SHORT_LIVED_SESSIONS = True
  188. Short lived sessions are disabled by default. If enabled they can drastically reduce
  189. performance, especially on systems processing lots of tasks. This option is useful
  190. on low-traffic workers that experience errors as a result of cached database connections
  191. going stale through inactivity. For example, intermittent errors like
  192. `(OperationalError) (2006, 'MySQL server has gone away')` can be fixed by enabling
  193. short lived sessions. This option only affects the database backend.
  194. Specifying Table Names
  195. ~~~~~~~~~~~~~~~~~~~~~~
  196. .. setting:: CELERY_RESULT_DB_TABLENAMES
  197. When SQLAlchemy is configured as the result backend, Celery automatically
  198. creates two tables to store result metadata for tasks. This setting allows
  199. you to customize the table names:
  200. .. code-block:: python
  201. # use custom table names for the database result backend.
  202. CELERY_RESULT_DB_TABLENAMES = {
  203. 'task': 'myapp_taskmeta',
  204. 'group': 'myapp_groupmeta',
  205. }
  206. Example configuration
  207. ~~~~~~~~~~~~~~~~~~~~~
  208. .. code-block:: python
  209. CELERY_RESULT_BACKEND = "database"
  210. CELERY_RESULT_DBURI = "mysql://user:password@host/dbname"
  211. CELERY_RESULT_DB_TASK_TABLENAME = "myapp_taskmeta"
  212. CELERY_RESULT_DB_TASKSET_TABLENAME = "myapp_tasksetmeta"
  213. .. _conf-amqp-result-backend:
  214. AMQP backend settings
  215. ---------------------
  216. .. note::
  217. The AMQP backend requires RabbitMQ 1.1.0 or higher to automatically
  218. expire results. If you are running an older version of RabbitmQ
  219. you should disable result expiration like this:
  220. CELERY_TASK_RESULT_EXPIRES = None
  221. .. setting:: CELERY_RESULT_EXCHANGE
  222. CELERY_RESULT_EXCHANGE
  223. ~~~~~~~~~~~~~~~~~~~~~~
  224. Name of the exchange to publish results in. Default is `"celeryresults"`.
  225. .. setting:: CELERY_RESULT_EXCHANGE_TYPE
  226. CELERY_RESULT_EXCHANGE_TYPE
  227. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  228. The exchange type of the result exchange. Default is to use a `direct`
  229. exchange.
  230. .. setting:: CELERY_RESULT_PERSISTENT
  231. CELERY_RESULT_PERSISTENT
  232. ~~~~~~~~~~~~~~~~~~~~~~~~
  233. If set to :const:`True`, result messages will be persistent. This means the
  234. messages will not be lost after a broker restart. The default is for the
  235. results to be transient.
  236. Example configuration
  237. ~~~~~~~~~~~~~~~~~~~~~
  238. .. code-block:: python
  239. CELERY_RESULT_BACKEND = "amqp"
  240. CELERY_TASK_RESULT_EXPIRES = 18000 # 5 hours.
  241. .. _conf-cache-result-backend:
  242. Cache backend settings
  243. ----------------------
  244. .. note::
  245. The cache backend supports the `pylibmc`_ and `python-memcached`
  246. libraries. The latter is used only if `pylibmc`_ is not installed.
  247. .. setting:: CELERY_CACHE_BACKEND
  248. CELERY_CACHE_BACKEND
  249. ~~~~~~~~~~~~~~~~~~~~
  250. Using a single memcached server:
  251. .. code-block:: python
  252. CELERY_CACHE_BACKEND = 'memcached://127.0.0.1:11211/'
  253. Using multiple memcached servers:
  254. .. code-block:: python
  255. CELERY_RESULT_BACKEND = "cache"
  256. CELERY_CACHE_BACKEND = 'memcached://172.19.26.240:11211;172.19.26.242:11211/'
  257. .. setting:: CELERY_CACHE_BACKEND_OPTIONS
  258. The "memory" backend stores the cache in memory only:
  259. CELERY_CACHE_BACKEND = "memory"
  260. CELERY_CACHE_BACKEND_OPTIONS
  261. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  262. You can set pylibmc options using the :setting:`CELERY_CACHE_BACKEND_OPTIONS`
  263. setting:
  264. .. code-block:: python
  265. CELERY_CACHE_BACKEND_OPTIONS = {"binary": True,
  266. "behaviors": {"tcp_nodelay": True}}
  267. .. _`pylibmc`: http://sendapatch.se/projects/pylibmc/
  268. .. _conf-redis-result-backend:
  269. Redis backend settings
  270. ----------------------
  271. Configuring the backend URL
  272. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  273. .. note::
  274. The Redis backend requires the :mod:`redis` library:
  275. http://pypi.python.org/pypi/redis/
  276. To install the redis package use `pip` or `easy_install`:
  277. .. code-block:: bash
  278. $ pip install redis
  279. This backend requires the :setting:`CELERY_RESULT_BACKEND`
  280. setting to be set to a Redis URL::
  281. CELERY_RESULT_BACKEND = "redis://:password@host:port/db"
  282. For example::
  283. CELERY_RESULT_BACKEND = "redis://localhost/0"
  284. which is the same as::
  285. CELERY_RESULT_BACKEND = "redis://"
  286. The fields of the URL is defined as folows:
  287. - *host*
  288. Host name or IP address of the Redis server. e.g. `"localhost"`.
  289. - *port*
  290. Port to the Redis server. Default is 6379.
  291. - *db*
  292. Database number to use. Default is 0.
  293. The db can include an optional leading slash.
  294. - *password*
  295. Password used to connect to the database.
  296. .. setting:: CELERY_REDIS_MAX_CONNECTIONS
  297. CELERY_REDIS_MAX_CONNECTIONS
  298. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  299. Maximum number of connections available in the Redis connection
  300. pool used for sending and retrieving results.
  301. .. _conf-mongodb-result-backend:
  302. MongoDB backend settings
  303. ------------------------
  304. .. note::
  305. The MongoDB backend requires the :mod:`pymongo` library:
  306. http://github.com/mongodb/mongo-python-driver/tree/master
  307. .. setting:: CELERY_MONGODB_BACKEND_SETTINGS
  308. CELERY_MONGODB_BACKEND_SETTINGS
  309. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  310. This is a dict supporting the following keys:
  311. * host
  312. Host name of the MongoDB server. Defaults to "localhost".
  313. * port
  314. The port the MongoDB server is listening to. Defaults to 27017.
  315. * user
  316. User name to authenticate to the MongoDB server as (optional).
  317. * password
  318. Password to authenticate to the MongoDB server (optional).
  319. * database
  320. The database name to connect to. Defaults to "celery".
  321. * taskmeta_collection
  322. The collection name to store task meta data.
  323. Defaults to "celery_taskmeta".
  324. * max_pool_size
  325. Passed as max_pool_size to PyMongo's Connection or MongoClient
  326. constructor. It is the maximum number of TCP connections to keep
  327. open to MongoDB at a given time. If there are more open connections
  328. than max_pool_size, sockets will be closed when they are released.
  329. Defaults to 10.
  330. * options
  331. Additional keyword arguments to pass to the mongodb connection
  332. constructor. See the :mod:`pymongo` docs to see a list of arguments
  333. supported.
  334. .. _example-mongodb-result-config:
  335. Example configuration
  336. ~~~~~~~~~~~~~~~~~~~~~
  337. .. code-block:: python
  338. CELERY_RESULT_BACKEND = "mongodb"
  339. CELERY_MONGODB_BACKEND_SETTINGS = {
  340. "host": "192.168.1.100",
  341. "port": 30000,
  342. "database": "mydb",
  343. "taskmeta_collection": "my_taskmeta_collection",
  344. }
  345. .. _conf-cassandra-result-backend:
  346. Cassandra backend settings
  347. --------------------------
  348. .. note::
  349. The Cassandra backend requires the :mod:`pycassa` library:
  350. http://pypi.python.org/pypi/pycassa/
  351. To install the pycassa package use `pip` or `easy_install`:
  352. .. code-block:: bash
  353. $ pip install pycassa
  354. This backend requires the following configuration directives to be set.
  355. .. setting:: CASSANDRA_SERVERS
  356. CASSANDRA_SERVERS
  357. ~~~~~~~~~~~~~~~~~
  358. List of ``host:port`` Cassandra servers. e.g. ``["localhost:9160]"``.
  359. .. setting:: CASSANDRA_KEYSPACE
  360. CASSANDRA_KEYSPACE
  361. ~~~~~~~~~~~~~~~~~~
  362. The keyspace in which to store the results. e.g. ``"tasks_keyspace"``.
  363. .. setting:: CASSANDRA_COLUMN_FAMILY
  364. CASSANDRA_COLUMN_FAMILY
  365. ~~~~~~~~~~~~~~~~~~~~~~~
  366. The column family in which to store the results. eg ``"tasks"``
  367. .. setting:: CASSANDRA_READ_CONSISTENCY
  368. CASSANDRA_READ_CONSISTENCY
  369. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  370. The read consistency used. Values can be ``"ONE"``, ``"QUORUM"`` or ``"ALL"``.
  371. .. setting:: CASSANDRA_WRITE_CONSISTENCY
  372. CASSANDRA_WRITE_CONSISTENCY
  373. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  374. The write consistency used. Values can be ``"ONE"``, ``"QUORUM"`` or ``"ALL"``.
  375. .. setting:: CASSANDRA_DETAILED_MODE
  376. CASSANDRA_DETAILED_MODE
  377. ~~~~~~~~~~~~~~~~~~~~~~~
  378. Enable or disable detailed mode. Default is :const:`False`.
  379. This mode allows to use the power of Cassandra wide columns to
  380. store all states for a task as a wide column, instead of only the last one.
  381. To use this mode, you need to configure your ColumnFamily to
  382. use the ``TimeUUID`` type as a comparator::
  383. create column family task_results with comparator = TimeUUIDType;
  384. CASSANDRA_OPTIONS
  385. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  386. Options to be passed to the `pycassa connection pool`_ (optional).
  387. .. _`pycassa connection pool`: http://pycassa.github.com/pycassa/api/pycassa/pool.html
  388. Example configuration
  389. ~~~~~~~~~~~~~~~~~~~~~
  390. .. code-block:: python
  391. CASSANDRA_SERVERS = ["localhost:9160"]
  392. CASSANDRA_KEYSPACE = "celery"
  393. CASSANDRA_COLUMN_FAMILY = "task_results"
  394. CASSANDRA_READ_CONSISTENCY = "ONE"
  395. CASSANDRA_WRITE_CONSISTENCY = "ONE"
  396. CASSANDRA_DETAILED_MODE = True
  397. CASSANDRA_OPTIONS = {
  398. 'timeout': 300,
  399. 'max_retries': 10
  400. }
  401. .. _conf-ironcache-result-backend:
  402. IronCache backend settings
  403. --------------------------
  404. .. note::
  405. The IronCache backend requires the :mod:`iron_celery` library:
  406. http://pypi.python.org/pypi/iron_celery
  407. To install the iron_celery package use `pip` or `easy_install`:
  408. .. code-block:: bash
  409. $ pip install iron_celery
  410. IronCache is configured via the URL provided in :setting:`CELERY_RESULT_BACKEND`, for example::
  411. CELERY_RESULT_BACKEND = 'ironcache://project_id:token@'
  412. Or to change the cache name::
  413. ironcache:://project_id:token@/awesomecache
  414. For more information, see: https://github.com/iron-io/iron_celery
  415. . _conf-couchbase-result-backend:
  416. Couchbase backend settings
  417. --------------------------
  418. .. note::
  419. The Couchbase backend requires the :mod:`couchbase` library:
  420. https://pypi.python.org/pypi/couchbase
  421. To install the couchbase package use `pip` or `easy_install`:
  422. .. code-block:: bash
  423. $ pip install couchbase
  424. This backend can be configured via the :setting:`CELERY_RESULT_BACKEND`
  425. set to a couchbase URL::
  426. CELERY_RESULT_BACKEND = "couchbase://username:password@host:port/bucket"
  427. .. setting:: CELERY_COUCHBASE_BACKEND_SETTINGS
  428. CELERY_COUCHBASE_BACKEND_SETTINGS
  429. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  430. This is a dict supporting the following keys:
  431. * host
  432. Host name of the Couchbase server. Defaults to "localhost".
  433. * port
  434. The port the Couchbase server is listening to. Defaults to 8091.
  435. * bucket
  436. The default bucket the Couchbase server is writing to. Defaults to "default".
  437. * username
  438. User name to authenticate to the Couchbase server as (optional).
  439. * password
  440. Password to authenticate to the Couchbase server (optional).
  441. .. _conf-messaging:
  442. Message Routing
  443. ---------------
  444. .. _conf-messaging-routing:
  445. .. setting:: CELERY_QUEUES
  446. CELERY_QUEUES
  447. ~~~~~~~~~~~~~
  448. The mapping of queues the worker consumes from. This is a dictionary
  449. of queue name/options. See :ref:`guide-routing` for more information.
  450. The default is a queue/exchange/binding key of `"celery"`, with
  451. exchange type `direct`.
  452. You don't have to care about this unless you want custom routing facilities.
  453. .. setting:: CELERY_ROUTES
  454. CELERY_ROUTES
  455. ~~~~~~~~~~~~~
  456. A list of routers, or a single router used to route tasks to queues.
  457. When deciding the final destination of a task the routers are consulted
  458. in order. See :ref:`routers` for more information.
  459. .. setting:: CELERY_QUEUE_HA_POLICY
  460. CELERY_QUEUE_HA_POLICY
  461. ~~~~~~~~~~~~~~~~~~~~~~
  462. :brokers: RabbitMQ
  463. This will set the default HA policy for a queue, and the value
  464. can either be a string (usually ``all``):
  465. .. code-block:: python
  466. CELERY_QUEUE_HA_POLICY = 'all'
  467. Using 'all' will replicate the queue to all current nodes,
  468. Or you can give it a list of nodes to replicate to:
  469. .. code-block:: python
  470. CELERY_QUEUE_HA_POLICY = ['rabbit@host1', 'rabbit@host2']
  471. Using a list will implicitly set ``x-ha-policy`` to 'nodes' and
  472. ``x-ha-policy-params`` to the given list of nodes.
  473. See http://www.rabbitmq.com/ha.html for more information.
  474. .. setting:: CELERY_WORKER_DIRECT
  475. CELERY_WORKER_DIRECT
  476. ~~~~~~~~~~~~~~~~~~~~
  477. This option enables so that every worker has a dedicated queue,
  478. so that tasks can be routed to specific workers.
  479. The queue name for each worker is automatically generated based on
  480. the worker hostname and a ``.dq`` suffix, using the ``C.dq`` exchange.
  481. For example the queue name for the worker with hostname ``w1.example.com``
  482. becomes::
  483. w1.example.com.dq
  484. Then you can route the task to the task by specifying the hostname
  485. as the routing key and the ``C.dq`` exchange::
  486. CELERY_ROUTES = {
  487. 'tasks.add': {'exchange': 'C.dq', 'routing_key': 'w1.example.com'}
  488. }
  489. .. setting:: CELERY_CREATE_MISSING_QUEUES
  490. CELERY_CREATE_MISSING_QUEUES
  491. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  492. If enabled (default), any queues specified that are not defined in
  493. :setting:`CELERY_QUEUES` will be automatically created. See
  494. :ref:`routing-automatic`.
  495. .. setting:: CELERY_DEFAULT_QUEUE
  496. CELERY_DEFAULT_QUEUE
  497. ~~~~~~~~~~~~~~~~~~~~
  498. The name of the default queue used by `.apply_async` if the message has
  499. no route or no custom queue has been specified.
  500. This queue must be listed in :setting:`CELERY_QUEUES`.
  501. If :setting:`CELERY_QUEUES` is not specified then it is automatically
  502. created containing one queue entry, where this name is used as the name of
  503. that queue.
  504. The default is: `celery`.
  505. .. seealso::
  506. :ref:`routing-changing-default-queue`
  507. .. setting:: CELERY_DEFAULT_EXCHANGE
  508. CELERY_DEFAULT_EXCHANGE
  509. ~~~~~~~~~~~~~~~~~~~~~~~
  510. Name of the default exchange to use when no custom exchange is
  511. specified for a key in the :setting:`CELERY_QUEUES` setting.
  512. The default is: `celery`.
  513. .. setting:: CELERY_DEFAULT_EXCHANGE_TYPE
  514. CELERY_DEFAULT_EXCHANGE_TYPE
  515. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  516. Default exchange type used when no custom exchange type is specified
  517. for a key in the :setting:`CELERY_QUEUES` setting.
  518. The default is: `direct`.
  519. .. setting:: CELERY_DEFAULT_ROUTING_KEY
  520. CELERY_DEFAULT_ROUTING_KEY
  521. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  522. The default routing key used when no custom routing key
  523. is specified for a key in the :setting:`CELERY_QUEUES` setting.
  524. The default is: `celery`.
  525. .. setting:: CELERY_DEFAULT_DELIVERY_MODE
  526. CELERY_DEFAULT_DELIVERY_MODE
  527. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  528. Can be `transient` or `persistent`. The default is to send
  529. persistent messages.
  530. .. _conf-broker-settings:
  531. Broker Settings
  532. ---------------
  533. .. setting:: CELERY_ACCEPT_CONTENT
  534. CELERY_ACCEPT_CONTENT
  535. ~~~~~~~~~~~~~~~~~~~~~
  536. A whitelist of content-types/serializers to allow.
  537. If a message is received that is not in this list then
  538. the message will be discarded with an error.
  539. By default any content type is enabled (including pickle and yaml)
  540. so make sure untrusted parties do not have access to your broker.
  541. See :ref:`guide-security` for more.
  542. Example::
  543. # using serializer name
  544. CELERY_ACCEPT_CONTENT = ['json']
  545. # or the actual content-type (MIME)
  546. CELERY_ACCEPT_CONTENT = ['application/json']
  547. .. setting:: BROKER_TRANSPORT
  548. BROKER_TRANSPORT
  549. ~~~~~~~~~~~~~~~~
  550. :Aliases: ``BROKER_BACKEND``
  551. :Deprecated aliases: ``CARROT_BACKEND``
  552. .. setting:: BROKER_URL
  553. BROKER_URL
  554. ~~~~~~~~~~
  555. Default broker URL. This must be an URL in the form of::
  556. transport://userid:password@hostname:port/virtual_host
  557. Only the scheme part (``transport://``) is required, the rest
  558. is optional, and defaults to the specific transports default values.
  559. The transport part is the broker implementation to use, and the
  560. default is ``amqp``, which uses ``librabbitmq`` by default or falls back to
  561. ``pyamqp`` if that is not installed. Also there are many other choices including
  562. ``redis``, ``beanstalk``, ``sqlalchemy``, ``django``, ``mongodb``,
  563. ``couchdb``.
  564. It can also be a fully qualified path to your own transport implementation.
  565. See :ref:`kombu:connection-urls` in the Kombu documentation for more
  566. information.
  567. .. setting:: BROKER_HEARTBEAT
  568. BROKER_HEARTBEAT
  569. ~~~~~~~~~~~~~~~~
  570. :transports supported: ``pyamqp``
  571. It's not always possible to detect connection loss in a timely
  572. manner using TCP/IP alone, so AMQP defines something called heartbeats
  573. that's is used both by the client and the broker to detect if
  574. a connection was closed.
  575. Hartbeats are disabled by default.
  576. If the heartbeat value is 10 seconds, then
  577. the heartbeat will be monitored at the interval specified
  578. by the :setting:`BROKER_HEARTBEAT_CHECKRATE` setting, which by default is
  579. double the rate of the heartbeat value
  580. (so for the default 10 seconds, the heartbeat is checked every 5 seconds).
  581. .. setting:: BROKER_HEARTBEAT_CHECKRATE
  582. BROKER_HEARTBEAT_CHECKRATE
  583. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  584. :transports supported: ``pyamqp``
  585. At intervals the worker will monitor that the broker has not missed
  586. too many heartbeats. The rate at which this is checked is calculated
  587. by dividing the :setting:`BROKER_HEARTBEAT` value with this value,
  588. so if the heartbeat is 10.0 and the rate is the default 2.0, the check
  589. will be performed every 5 seconds (twice the heartbeat sending rate).
  590. .. setting:: BROKER_USE_SSL
  591. BROKER_USE_SSL
  592. ~~~~~~~~~~~~~~
  593. Use SSL to connect to the broker. Off by default. This may not be supported
  594. by all transports.
  595. .. setting:: BROKER_POOL_LIMIT
  596. BROKER_POOL_LIMIT
  597. ~~~~~~~~~~~~~~~~~
  598. .. versionadded:: 2.3
  599. The maximum number of connections that can be open in the connection pool.
  600. The pool is enabled by default since version 2.5, with a default limit of ten
  601. connections. This number can be tweaked depending on the number of
  602. threads/greenthreads (eventlet/gevent) using a connection. For example
  603. running eventlet with 1000 greenlets that use a connection to the broker,
  604. contention can arise and you should consider increasing the limit.
  605. If set to :const:`None` or 0 the connection pool will be disabled and
  606. connections will be established and closed for every use.
  607. Default (since 2.5) is to use a pool of 10 connections.
  608. .. setting:: BROKER_CONNECTION_TIMEOUT
  609. BROKER_CONNECTION_TIMEOUT
  610. ~~~~~~~~~~~~~~~~~~~~~~~~~
  611. The default timeout in seconds before we give up establishing a connection
  612. to the AMQP server. Default is 4 seconds.
  613. .. setting:: BROKER_CONNECTION_RETRY
  614. BROKER_CONNECTION_RETRY
  615. ~~~~~~~~~~~~~~~~~~~~~~~
  616. Automatically try to re-establish the connection to the AMQP broker if lost.
  617. The time between retries is increased for each retry, and is
  618. not exhausted before :setting:`BROKER_CONNECTION_MAX_RETRIES` is
  619. exceeded.
  620. This behavior is on by default.
  621. .. setting:: BROKER_CONNECTION_MAX_RETRIES
  622. BROKER_CONNECTION_MAX_RETRIES
  623. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  624. Maximum number of retries before we give up re-establishing a connection
  625. to the AMQP broker.
  626. If this is set to :const:`0` or :const:`None`, we will retry forever.
  627. Default is 100 retries.
  628. .. setting:: BROKER_LOGIN_METHOD
  629. BROKER_LOGIN_METHOD
  630. ~~~~~~~~~~~~~~~~~~~
  631. Set custom amqp login method, default is ``AMQPLAIN``.
  632. .. setting:: BROKER_TRANSPORT_OPTIONS
  633. BROKER_TRANSPORT_OPTIONS
  634. ~~~~~~~~~~~~~~~~~~~~~~~~
  635. .. versionadded:: 2.2
  636. A dict of additional options passed to the underlying transport.
  637. See your transport user manual for supported options (if any).
  638. Example setting the visibility timeout (supported by Redis and SQS
  639. transports):
  640. .. code-block:: python
  641. BROKER_TRANSPORT_OPTIONS = {'visibility_timeout': 18000} # 5 hours
  642. .. _conf-task-execution:
  643. Task execution settings
  644. -----------------------
  645. .. setting:: CELERY_ALWAYS_EAGER
  646. CELERY_ALWAYS_EAGER
  647. ~~~~~~~~~~~~~~~~~~~
  648. If this is :const:`True`, all tasks will be executed locally by blocking until
  649. the task returns. ``apply_async()`` and ``Task.delay()`` will return
  650. an :class:`~celery.result.EagerResult` instance, which emulates the API
  651. and behavior of :class:`~celery.result.AsyncResult`, except the result
  652. is already evaluated.
  653. That is, tasks will be executed locally instead of being sent to
  654. the queue.
  655. .. setting:: CELERY_EAGER_PROPAGATES_EXCEPTIONS
  656. CELERY_EAGER_PROPAGATES_EXCEPTIONS
  657. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  658. If this is :const:`True`, eagerly executed tasks (applied by `task.apply()`,
  659. or when the :setting:`CELERY_ALWAYS_EAGER` setting is enabled), will
  660. propagate exceptions.
  661. It's the same as always running ``apply()`` with ``throw=True``.
  662. .. setting:: CELERY_IGNORE_RESULT
  663. CELERY_IGNORE_RESULT
  664. ~~~~~~~~~~~~~~~~~~~~
  665. Whether to store the task return values or not (tombstones).
  666. If you still want to store errors, just not successful return values,
  667. you can set :setting:`CELERY_STORE_ERRORS_EVEN_IF_IGNORED`.
  668. .. setting:: CELERY_MESSAGE_COMPRESSION
  669. CELERY_MESSAGE_COMPRESSION
  670. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  671. Default compression used for task messages.
  672. Can be ``"gzip"``, ``"bzip2"`` (if available), or any custom
  673. compression schemes registered in the Kombu compression registry.
  674. The default is to send uncompressed messages.
  675. .. setting:: CELERY_TASK_RESULT_EXPIRES
  676. CELERY_TASK_RESULT_EXPIRES
  677. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  678. Time (in seconds, or a :class:`~datetime.timedelta` object) for when after
  679. stored task tombstones will be deleted.
  680. A built-in periodic task will delete the results after this time
  681. (:class:`celery.task.backend_cleanup`).
  682. A value of :const:`None` or 0 means results will never expire (depending
  683. on backend specifications).
  684. Default is to expire after 1 day.
  685. .. note::
  686. For the moment this only works with the amqp, database, cache, redis and MongoDB
  687. backends.
  688. When using the database or MongoDB backends, `celery beat` must be
  689. running for the results to be expired.
  690. .. setting:: CELERY_MAX_CACHED_RESULTS
  691. CELERY_MAX_CACHED_RESULTS
  692. ~~~~~~~~~~~~~~~~~~~~~~~~~
  693. Result backends caches ready results used by the client.
  694. This is the total number of results to cache before older results are evicted.
  695. The default is 5000.
  696. .. setting:: CELERY_CHORD_PROPAGATES
  697. CELERY_CHORD_PROPAGATES
  698. ~~~~~~~~~~~~~~~~~~~~~~~
  699. .. versionadded:: 3.0.14
  700. This setting defines what happens when a task part of a chord raises an
  701. exception:
  702. - If propagate is True the chord callback will change state to FAILURE
  703. with the exception value set to a :exc:`~celery.exceptions.ChordError`
  704. instance containing information about the error and the task that failed.
  705. This is the default behavior in Celery 3.1+
  706. - If propagate is False the exception value will instead be forwarded
  707. to the chord callback.
  708. This was the default behavior before version 3.1.
  709. .. setting:: CELERY_TRACK_STARTED
  710. CELERY_TRACK_STARTED
  711. ~~~~~~~~~~~~~~~~~~~~
  712. If :const:`True` the task will report its status as "started" when the
  713. task is executed by a worker. The default value is :const:`False` as
  714. the normal behaviour is to not report that level of granularity. Tasks
  715. are either pending, finished, or waiting to be retried. Having a "started"
  716. state can be useful for when there are long running tasks and there is a
  717. need to report which task is currently running.
  718. .. setting:: CELERY_TASK_SERIALIZER
  719. CELERY_TASK_SERIALIZER
  720. ~~~~~~~~~~~~~~~~~~~~~~
  721. A string identifying the default serialization method to use. Can be
  722. `pickle` (default), `json`, `yaml`, `msgpack` or any custom serialization
  723. methods that have been registered with :mod:`kombu.serialization.registry`.
  724. .. seealso::
  725. :ref:`calling-serializers`.
  726. .. setting:: CELERY_TASK_PUBLISH_RETRY
  727. CELERY_TASK_PUBLISH_RETRY
  728. ~~~~~~~~~~~~~~~~~~~~~~~~~
  729. .. versionadded:: 2.2
  730. Decides if publishing task messages will be retried in the case
  731. of connection loss or other connection errors.
  732. See also :setting:`CELERY_TASK_PUBLISH_RETRY_POLICY`.
  733. Enabled by default.
  734. .. setting:: CELERY_TASK_PUBLISH_RETRY_POLICY
  735. CELERY_TASK_PUBLISH_RETRY_POLICY
  736. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  737. .. versionadded:: 2.2
  738. Defines the default policy when retrying publishing a task message in
  739. the case of connection loss or other connection errors.
  740. See :ref:`calling-retry` for more information.
  741. .. setting:: CELERY_DEFAULT_RATE_LIMIT
  742. CELERY_DEFAULT_RATE_LIMIT
  743. ~~~~~~~~~~~~~~~~~~~~~~~~~
  744. The global default rate limit for tasks.
  745. This value is used for tasks that does not have a custom rate limit
  746. The default is no rate limit.
  747. .. setting:: CELERY_DISABLE_RATE_LIMITS
  748. CELERY_DISABLE_RATE_LIMITS
  749. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  750. Disable all rate limits, even if tasks has explicit rate limits set.
  751. .. setting:: CELERY_ACKS_LATE
  752. CELERY_ACKS_LATE
  753. ~~~~~~~~~~~~~~~~
  754. Late ack means the task messages will be acknowledged **after** the task
  755. has been executed, not *just before*, which is the default behavior.
  756. .. seealso::
  757. FAQ: :ref:`faq-acks_late-vs-retry`.
  758. .. _conf-worker:
  759. Worker
  760. ------
  761. .. setting:: CELERY_IMPORTS
  762. CELERY_IMPORTS
  763. ~~~~~~~~~~~~~~
  764. A sequence of modules to import when the worker starts.
  765. This is used to specify the task modules to import, but also
  766. to import signal handlers and additional remote control commands, etc.
  767. The modules will be imported in the original order.
  768. .. setting:: CELERY_INCLUDE
  769. CELERY_INCLUDE
  770. ~~~~~~~~~~~~~~
  771. Exact same semantics as :setting:`CELERY_IMPORTS`, but can be used as a means
  772. to have different import categories.
  773. The modules in this setting are imported after the modules in
  774. :setting:`CELERY_IMPORTS`.
  775. .. setting:: CELERYD_FORCE_EXECV
  776. CELERYD_FORCE_EXECV
  777. ~~~~~~~~~~~~~~~~~~~
  778. On Unix the processes pool will fork, so that child processes
  779. start with the same memory as the parent process.
  780. This can cause problems as there is a known deadlock condition
  781. with pthread locking primitives when `fork()` is combined with threads.
  782. You should enable this setting if you are experiencing hangs (deadlocks),
  783. especially in combination with time limits or having a max tasks per child limit.
  784. This option will be enabled by default in a later version.
  785. This is not a problem on Windows, as it does not have `fork()`.
  786. .. setting:: CELERYD_WORKER_LOST_WAIT
  787. CELERYD_WORKER_LOST_WAIT
  788. ~~~~~~~~~~~~~~~~~~~~~~~~
  789. In some cases a worker may be killed without proper cleanup,
  790. and the worker may have published a result before terminating.
  791. This value specifies how long we wait for any missing results before
  792. raising a :exc:`@WorkerLostError` exception.
  793. Default is 10.0
  794. .. setting:: CELERYD_MAX_TASKS_PER_CHILD
  795. CELERYD_MAX_TASKS_PER_CHILD
  796. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  797. Maximum number of tasks a pool worker process can execute before
  798. it's replaced with a new one. Default is no limit.
  799. .. setting:: CELERYD_TASK_TIME_LIMIT
  800. CELERYD_TASK_TIME_LIMIT
  801. ~~~~~~~~~~~~~~~~~~~~~~~
  802. Task hard time limit in seconds. The worker processing the task will
  803. be killed and replaced with a new one when this is exceeded.
  804. .. setting:: CELERYD_TASK_SOFT_TIME_LIMIT
  805. CELERYD_TASK_SOFT_TIME_LIMIT
  806. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  807. Task soft time limit in seconds.
  808. The :exc:`~@SoftTimeLimitExceeded` exception will be
  809. raised when this is exceeded. The task can catch this to
  810. e.g. clean up before the hard time limit comes.
  811. Example:
  812. .. code-block:: python
  813. from celery.exceptions import SoftTimeLimitExceeded
  814. @celery.task
  815. def mytask():
  816. try:
  817. return do_work()
  818. except SoftTimeLimitExceeded:
  819. cleanup_in_a_hurry()
  820. .. setting:: CELERY_STORE_ERRORS_EVEN_IF_IGNORED
  821. CELERY_STORE_ERRORS_EVEN_IF_IGNORED
  822. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  823. If set, the worker stores all task errors in the result store even if
  824. :attr:`Task.ignore_result <celery.task.base.Task.ignore_result>` is on.
  825. .. setting:: CELERYD_STATE_DB
  826. CELERYD_STATE_DB
  827. ~~~~~~~~~~~~~~~~
  828. Name of the file used to stores persistent worker state (like revoked tasks).
  829. Can be a relative or absolute path, but be aware that the suffix `.db`
  830. may be appended to the file name (depending on Python version).
  831. Can also be set via the :option:`--statedb` argument to
  832. :mod:`~celery.bin.worker`.
  833. Not enabled by default.
  834. .. setting:: CELERYD_TIMER_PRECISION
  835. CELERYD_TIMER_PRECISION
  836. ~~~~~~~~~~~~~~~~~~~~~~~
  837. Set the maximum time in seconds that the ETA scheduler can sleep between
  838. rechecking the schedule. Default is 1 second.
  839. Setting this value to 1 second means the schedulers precision will
  840. be 1 second. If you need near millisecond precision you can set this to 0.1.
  841. .. setting:: CELERY_ENABLE_REMOTE_CONTROL
  842. CELERY_ENABLE_REMOTE_CONTROL
  843. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  844. Specify if remote control of the workers is enabled.
  845. Default is :const:`True`.
  846. .. _conf-error-mails:
  847. Error E-Mails
  848. -------------
  849. .. setting:: CELERY_SEND_TASK_ERROR_EMAILS
  850. CELERY_SEND_TASK_ERROR_EMAILS
  851. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  852. The default value for the `Task.send_error_emails` attribute, which if
  853. set to :const:`True` means errors occurring during task execution will be
  854. sent to :setting:`ADMINS` by email.
  855. Disabled by default.
  856. .. setting:: ADMINS
  857. ADMINS
  858. ~~~~~~
  859. List of `(name, email_address)` tuples for the administrators that should
  860. receive error emails.
  861. .. setting:: SERVER_EMAIL
  862. SERVER_EMAIL
  863. ~~~~~~~~~~~~
  864. The email address this worker sends emails from.
  865. Default is celery@localhost.
  866. .. setting:: EMAIL_HOST
  867. EMAIL_HOST
  868. ~~~~~~~~~~
  869. The mail server to use. Default is `"localhost"`.
  870. .. setting:: EMAIL_HOST_USER
  871. EMAIL_HOST_USER
  872. ~~~~~~~~~~~~~~~
  873. User name (if required) to log on to the mail server with.
  874. .. setting:: EMAIL_HOST_PASSWORD
  875. EMAIL_HOST_PASSWORD
  876. ~~~~~~~~~~~~~~~~~~~
  877. Password (if required) to log on to the mail server with.
  878. .. setting:: EMAIL_PORT
  879. EMAIL_PORT
  880. ~~~~~~~~~~
  881. The port the mail server is listening on. Default is `25`.
  882. .. setting:: EMAIL_USE_SSL
  883. EMAIL_USE_SSL
  884. ~~~~~~~~~~~~~
  885. Use SSL when connecting to the SMTP server. Disabled by default.
  886. .. setting:: EMAIL_USE_TLS
  887. EMAIL_USE_TLS
  888. ~~~~~~~~~~~~~
  889. Use TLS when connecting to the SMTP server. Disabled by default.
  890. .. setting:: EMAIL_TIMEOUT
  891. EMAIL_TIMEOUT
  892. ~~~~~~~~~~~~~
  893. Timeout in seconds for when we give up trying to connect
  894. to the SMTP server when sending emails.
  895. The default is 2 seconds.
  896. .. _conf-example-error-mail-config:
  897. Example E-Mail configuration
  898. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  899. This configuration enables the sending of error emails to
  900. george@vandelay.com and kramer@vandelay.com:
  901. .. code-block:: python
  902. # Enables error emails.
  903. CELERY_SEND_TASK_ERROR_EMAILS = True
  904. # Name and email addresses of recipients
  905. ADMINS = (
  906. ("George Costanza", "george@vandelay.com"),
  907. ("Cosmo Kramer", "kosmo@vandelay.com"),
  908. )
  909. # Email address used as sender (From field).
  910. SERVER_EMAIL = "no-reply@vandelay.com"
  911. # Mailserver configuration
  912. EMAIL_HOST = "mail.vandelay.com"
  913. EMAIL_PORT = 25
  914. # EMAIL_HOST_USER = "servers"
  915. # EMAIL_HOST_PASSWORD = "s3cr3t"
  916. .. _conf-events:
  917. Events
  918. ------
  919. .. setting:: CELERY_SEND_EVENTS
  920. CELERY_SEND_EVENTS
  921. ~~~~~~~~~~~~~~~~~~
  922. Send events so the worker can be monitored by tools like `celerymon`.
  923. .. setting:: CELERY_SEND_TASK_SENT_EVENT
  924. CELERY_SEND_TASK_SENT_EVENT
  925. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  926. .. versionadded:: 2.2
  927. If enabled, a :event:`task-sent` event will be sent for every task so tasks can be
  928. tracked before they are consumed by a worker.
  929. Disabled by default.
  930. .. setting:: CELERY_EVENT_QUEUE_TTL
  931. CELERY_EVENT_QUEUE_TTL
  932. ~~~~~~~~~~~~~~~~~~~~~~
  933. :transports supported: ``amqp``
  934. Message expiry time in seconds (int/float) for when messages sent to a monitor clients
  935. event queue is deleted (``x-message-ttl``)
  936. For example, if this value is set to 10 then a message delivered to this queue
  937. will be deleted after 10 seconds.
  938. Disabled by default.
  939. .. setting:: CELERY_EVENT_QUEUE_EXPIRES
  940. CELERY_EVENT_QUEUE_EXPIRES
  941. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  942. :transports supported: ``amqp``
  943. Expiry time in seconds (int/float) for when a monitor clients
  944. event queue will be deleted (``x-expires``).
  945. Default is never, relying on the queue autodelete setting.
  946. .. setting:: CELERY_EVENT_SERIALIZER
  947. CELERY_EVENT_SERIALIZER
  948. ~~~~~~~~~~~~~~~~~~~~~~~
  949. Message serialization format used when sending event messages.
  950. Default is `"json"`. See :ref:`calling-serializers`.
  951. .. _conf-broadcast:
  952. Broadcast Commands
  953. ------------------
  954. .. setting:: CELERY_BROADCAST_QUEUE
  955. CELERY_BROADCAST_QUEUE
  956. ~~~~~~~~~~~~~~~~~~~~~~
  957. Name prefix for the queue used when listening for broadcast messages.
  958. The workers host name will be appended to the prefix to create the final
  959. queue name.
  960. Default is `"celeryctl"`.
  961. .. setting:: CELERY_BROADCAST_EXCHANGE
  962. CELERY_BROADCAST_EXCHANGE
  963. ~~~~~~~~~~~~~~~~~~~~~~~~~
  964. Name of the exchange used for broadcast messages.
  965. Default is `"celeryctl"`.
  966. .. setting:: CELERY_BROADCAST_EXCHANGE_TYPE
  967. CELERY_BROADCAST_EXCHANGE_TYPE
  968. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  969. Exchange type used for broadcast messages. Default is `"fanout"`.
  970. .. _conf-logging:
  971. Logging
  972. -------
  973. .. setting:: CELERYD_HIJACK_ROOT_LOGGER
  974. CELERYD_HIJACK_ROOT_LOGGER
  975. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  976. .. versionadded:: 2.2
  977. By default any previously configured handlers on the root logger will be
  978. removed. If you want to customize your own logging handlers, then you
  979. can disable this behavior by setting
  980. `CELERYD_HIJACK_ROOT_LOGGER = False`.
  981. .. note::
  982. Logging can also be customized by connecting to the
  983. :signal:`celery.signals.setup_logging` signal.
  984. .. setting:: CELERYD_LOG_COLOR
  985. CELERYD_LOG_COLOR
  986. ~~~~~~~~~~~~~~~~~
  987. Enables/disables colors in logging output by the Celery apps.
  988. By default colors are enabled if
  989. 1) the app is logging to a real terminal, and not a file.
  990. 2) the app is not running on Windows.
  991. .. setting:: CELERYD_LOG_FORMAT
  992. CELERYD_LOG_FORMAT
  993. ~~~~~~~~~~~~~~~~~~
  994. The format to use for log messages.
  995. Default is `[%(asctime)s: %(levelname)s/%(processName)s] %(message)s`
  996. See the Python :mod:`logging` module for more information about log
  997. formats.
  998. .. setting:: CELERYD_TASK_LOG_FORMAT
  999. CELERYD_TASK_LOG_FORMAT
  1000. ~~~~~~~~~~~~~~~~~~~~~~~
  1001. The format to use for log messages logged in tasks. Can be overridden using
  1002. the :option:`--loglevel` option to :mod:`~celery.bin.worker`.
  1003. Default is::
  1004. [%(asctime)s: %(levelname)s/%(processName)s]
  1005. [%(task_name)s(%(task_id)s)] %(message)s
  1006. See the Python :mod:`logging` module for more information about log
  1007. formats.
  1008. .. setting:: CELERY_REDIRECT_STDOUTS
  1009. CELERY_REDIRECT_STDOUTS
  1010. ~~~~~~~~~~~~~~~~~~~~~~~
  1011. If enabled `stdout` and `stderr` will be redirected
  1012. to the current logger.
  1013. Enabled by default.
  1014. Used by :program:`celery worker` and :program:`celery beat`.
  1015. .. setting:: CELERY_REDIRECT_STDOUTS_LEVEL
  1016. CELERY_REDIRECT_STDOUTS_LEVEL
  1017. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1018. The log level output to `stdout` and `stderr` is logged as.
  1019. Can be one of :const:`DEBUG`, :const:`INFO`, :const:`WARNING`,
  1020. :const:`ERROR` or :const:`CRITICAL`.
  1021. Default is :const:`WARNING`.
  1022. .. setting:: CELERY_FORCE_BILLIARD_LOGGING
  1023. CELERY_FORCE_BILLIARD_LOGGING
  1024. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1025. .. versionadded:: 3.1
  1026. Celery uses :mod:`multiprocessing`'s fork called `billiard` as a pool
  1027. implementation. Python assumes we use :mod:`multiprocessing` when trying
  1028. to log `processName` though. By default this option forces Celery to modify
  1029. the logger class as early as possible in order to provide correct process
  1030. name in log messages. If you are going to use :mod:`multiprocessing` along
  1031. with Celery, you can disable this behavior by setting
  1032. `CELERY_FORCE_BILLIARD_LOGGING = False`.
  1033. Default is :const:`True`.
  1034. .. _conf-security:
  1035. Security
  1036. --------
  1037. .. setting:: CELERY_SECURITY_KEY
  1038. CELERY_SECURITY_KEY
  1039. ~~~~~~~~~~~~~~~~~~~
  1040. .. versionadded:: 2.5
  1041. The relative or absolute path to a file containing the private key
  1042. used to sign messages when :ref:`message-signing` is used.
  1043. .. setting:: CELERY_SECURITY_CERTIFICATE
  1044. CELERY_SECURITY_CERTIFICATE
  1045. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1046. .. versionadded:: 2.5
  1047. The relative or absolute path to an X.509 certificate file
  1048. used to sign messages when :ref:`message-signing` is used.
  1049. .. setting:: CELERY_SECURITY_CERT_STORE
  1050. CELERY_SECURITY_CERT_STORE
  1051. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  1052. .. versionadded:: 2.5
  1053. The directory containing X.509 certificates used for
  1054. :ref:`message-signing`. Can be a glob with wildcards,
  1055. (for example :file:`/etc/certs/*.pem`).
  1056. .. _conf-custom-components:
  1057. Custom Component Classes (advanced)
  1058. -----------------------------------
  1059. .. setting:: CELERYD_POOL
  1060. CELERYD_POOL
  1061. ~~~~~~~~~~~~
  1062. Name of the pool class used by the worker.
  1063. You can use a custom pool class name, or select one of
  1064. the built-in aliases: ``processes``, ``eventlet``, ``gevent``.
  1065. Default is ``processes``.
  1066. .. setting:: CELERYD_POOL_RESTARTS
  1067. CELERYD_POOL_RESTARTS
  1068. ~~~~~~~~~~~~~~~~~~~~~
  1069. If enabled the worker pool can be restarted using the
  1070. :control:`pool_restart` remote control command.
  1071. Disabled by default.
  1072. .. setting:: CELERYD_AUTOSCALER
  1073. CELERYD_AUTOSCALER
  1074. ~~~~~~~~~~~~~~~~~~
  1075. .. versionadded:: 2.2
  1076. Name of the autoscaler class to use.
  1077. Default is ``"celery.worker.autoscale.Autoscaler"``.
  1078. .. setting:: CELERYD_AUTORELOADER
  1079. CELERYD_AUTORELOADER
  1080. ~~~~~~~~~~~~~~~~~~~~
  1081. Name of the autoreloader class used by the worker to reload
  1082. Python modules and files that have changed.
  1083. Default is: ``"celery.worker.autoreload.Autoreloader"``.
  1084. .. setting:: CELERYD_CONSUMER
  1085. CELERYD_CONSUMER
  1086. ~~~~~~~~~~~~~~~~
  1087. Name of the consumer class used by the worker.
  1088. Default is :class:`celery.worker.consumer.Consumer`
  1089. .. setting:: CELERYD_TIMER
  1090. CELERYD_TIMER
  1091. ~~~~~~~~~~~~~~~~~~~~~
  1092. Name of the ETA scheduler class used by the worker.
  1093. Default is :class:`celery.utils.timer2.Timer`, or one overrided
  1094. by the pool implementation.
  1095. .. _conf-celerybeat:
  1096. Periodic Task Server: celery beat
  1097. ---------------------------------
  1098. .. setting:: CELERYBEAT_SCHEDULE
  1099. CELERYBEAT_SCHEDULE
  1100. ~~~~~~~~~~~~~~~~~~~
  1101. The periodic task schedule used by :mod:`~celery.bin.beat`.
  1102. See :ref:`beat-entries`.
  1103. .. setting:: CELERYBEAT_SCHEDULER
  1104. CELERYBEAT_SCHEDULER
  1105. ~~~~~~~~~~~~~~~~~~~~
  1106. The default scheduler class. Default is
  1107. `"celery.beat.PersistentScheduler"`.
  1108. Can also be set via the :option:`-S` argument to
  1109. :mod:`~celery.bin.beat`.
  1110. .. setting:: CELERYBEAT_SCHEDULE_FILENAME
  1111. CELERYBEAT_SCHEDULE_FILENAME
  1112. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1113. Name of the file used by `PersistentScheduler` to store the last run times
  1114. of periodic tasks. Can be a relative or absolute path, but be aware that the
  1115. suffix `.db` may be appended to the file name (depending on Python version).
  1116. Can also be set via the :option:`--schedule` argument to
  1117. :mod:`~celery.bin.beat`.
  1118. .. setting:: CELERYBEAT_MAX_LOOP_INTERVAL
  1119. CELERYBEAT_MAX_LOOP_INTERVAL
  1120. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1121. The maximum number of seconds :mod:`~celery.bin.beat` can sleep
  1122. between checking the schedule.
  1123. The default for this value is scheduler specific.
  1124. For the default celery beat scheduler the value is 300 (5 minutes),
  1125. but for e.g. the django-celery database scheduler it is 5 seconds
  1126. because the schedule may be changed externally, and so it must take
  1127. changes to the schedule into account.
  1128. Also when running celery beat embedded (:option:`-B`) on Jython as a thread
  1129. the max interval is overridden and set to 1 so that it's possible
  1130. to shut down in a timely manner.
  1131. .. _conf-celerymon:
  1132. Monitor Server: celerymon
  1133. -------------------------
  1134. .. setting:: CELERYMON_LOG_FORMAT
  1135. CELERYMON_LOG_FORMAT
  1136. ~~~~~~~~~~~~~~~~~~~~
  1137. The format to use for log messages.
  1138. Default is `[%(asctime)s: %(levelname)s/%(processName)s] %(message)s`
  1139. See the Python :mod:`logging` module for more information about log
  1140. formats.