Skip to content
This repository
Newer
Older
100644 709 lines (449 sloc) 24.534 kb
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
1 = Beanstalk Protocol =
2
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
3 Protocol
4 --------
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
5
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
6 The beanstalk protocol runs over TCP using ASCII encoding. Clients connect,
0670cf2d »
2007-12-17 Specify that commands are processed serially.
7 send commands and data, wait for responses, and close the connection. For each
8 connection, the server processes commands serially in the order in which they
9 were received and sends responses in the same order. All integers in the
10 protocol are formatted in decimal and (unless otherwise indicated)
11 nonnegative.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
12
c1b09c4f »
2008-02-20 Implement tubes.
13 Names, in this protocol, are ASCII strings. They may contain letters (A-Z and
14 a-z), numerals (0-9), hyphen ("-"), plus ("+"), slash ("/"), semicolon (";"),
88cd86be »
2010-02-28 Allow underscore in tube names.
15 dot ("."), dollar-sign ("$"), underscore ("_"), and parentheses ("(" and ")"),
16 but they may not begin with a hyphen. They are terminated by white space
17 (either a space char or end of line). Each name must be at least one character
18 long.
c1b09c4f »
2008-02-20 Implement tubes.
19
e59508dc »
2008-01-02 Reorder the paragraphs for better flow.
20 The protocol contains two kinds of data: text lines and unstructured chunks of
21 data. Text lines are used for client commands and server responses. Chunks are
22 used to transfer job bodies and stats information. Each job body is an opaque
23 sequence of bytes. The server never inspects or modifies a job body and always
24 sends it back in its original form. It is up to the clients to agree on a
25 meaningful interpretation of job bodies.
26
75c5269d »
2009-10-12 Fixed contradition re. quit command in protocol doc.
27 The client may issue the "quit" command, or simply close the TCP connection
28 when it no longer has use for the server. However, beanstalkd performs very
29 well with a large number of open connections, so it is usually better for the
30 client to keep its connection open and reuse it as much as possible. This also
31 avoids the overhead of establishing new TCP connections.
e59508dc »
2008-01-02 Reorder the paragraphs for better flow.
32
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
33 If a client violates the protocol (such as by sending a request that is not
582c8cf6 »
2008-01-02 Some proper error reporting.
34 well-formed or a command that does not exist) or if the server has an error,
2c25676e »
2008-01-02 Report errors just like all other messages.
35 the server will reply with one of the following error messages:
582c8cf6 »
2008-01-02 Some proper error reporting.
36
2c25676e »
2008-01-02 Report errors just like all other messages.
37 - "OUT_OF_MEMORY\r\n" The server cannot allocate enough memory for the job.
38 The client should try again later.
582c8cf6 »
2008-01-02 Some proper error reporting.
39
2c25676e »
2008-01-02 Report errors just like all other messages.
40 - "INTERNAL_ERROR\r\n" This indicates a bug in the server. It should never
41 happen. If it does happen, please report it at
42 http://groups.google.com/group/beanstalk-talk.
582c8cf6 »
2008-01-02 Some proper error reporting.
43
2c25676e »
2008-01-02 Report errors just like all other messages.
44 - "BAD_FORMAT\r\n" The client sent a command line that was not well-formed.
45 This can happen if the line does not end with \r\n, if non-numeric
46 characters occur where an integer is expected, if the wrong number of
47 arguments are present, or if the command line is mal-formed in any other
48 way.
582c8cf6 »
2008-01-02 Some proper error reporting.
49
2c25676e »
2008-01-02 Report errors just like all other messages.
50 - "UNKNOWN_COMMAND\r\n" The client sent a command that the server does not
51 know.
52
582c8cf6 »
2008-01-02 Some proper error reporting.
53 These error responses will not be listed in this document for individual
54 commands in the following sections, but they are implicitly included in the
55 description of all commands. Clients should be prepared to receive an error
56 response after any command.
57
58 As a last resort, if the server has a serious error that prevents it from
59 continuing service to the current client, the server will close the
60 connection.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
61
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
62 Job Lifecycle
63 -------------
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
64
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
65 A job in beanstalk gets created by a client with the "put" command. During its
80e0ff4a »
2007-12-10 Make "delayed" state name consistent.
66 life it can be in one of four states: "ready", "reserved", "delayed", or
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
67 "buried". After the put command, a job typically starts out ready. It waits in
68 the ready queue until a worker comes along and runs the "reserve" command. If
69 this job is next in the queue, it will be reserved for the worker. The worker
70 will execute the job; when it is finished the worker will send a "delete"
71 command to delete the job.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
72
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
73 Here is a picture of the typical job lifecycle:
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
74
75
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
76 put reserve delete
77 -----> [READY] ---------> [RESERVED] --------> *poof*
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
78
79
80
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
81 Here is a picture with more possibilities:
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
82
83
84
85 put with delay release with delay
86 ----------------> [DELAYED] <------------.
87 | |
88 | (time passes) |
89 | |
90 put v reserve | delete
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
91 -----------------> [READY] ---------> [RESERVED] --------> *poof*
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
92 ^ ^ | |
93 | \ release | |
94 | `-------------' |
95 | |
96 | kick |
97 | |
98 | bury |
99 [BURIED] <---------------'
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
100 |
101 | delete
102 `--------> *poof*
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
103
104
c1b09c4f »
2008-02-20 Implement tubes.
105 The system has one or more tubes. Each tube consists of a ready queue and a
106 delay queue. Each job spends its entire life in one tube. Consumers can show
107 interest in tubes by sending the "watch" command; they can show disinterest by
108 sending the "ignore" command. This set of interesting tubes is said to be a
109 consumer's "watch list". When a client reserves a job, it may come from any of
110 the tubes in its watch list.
111
112 When a client connects, its watch list is initially just the tube named
113 "default". If it submits jobs without having sent a "use" command, they will
114 live in the tube named "default".
115
116 Tubes are created on demand whenever they are referenced. If a tube is empty
117 (that is, it contains no ready, delayed, or buried jobs) and no client refers
118 to it, it will be deleted.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
119
c1b09c4f »
2008-02-20 Implement tubes.
120 Producer Commands
121 -----------------
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
122
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
123 The "put" command is for any process that wants to insert a job into the queue.
124 It comprises a command line followed by the job body:
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
125
f568f776 »
2007-12-17 Per-job timeouts. (#1310)
126 put <pri> <delay> <ttr> <bytes>\r\n
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
127 <data>\r\n
128
c1b09c4f »
2008-02-20 Implement tubes.
129 It inserts a job into the client's currently used tube (see the "use" command
130 below).
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
131
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
132 - <pri> is an integer < 2**32. Jobs with smaller priority values will be
133 scheduled before jobs with larger priorities. The most urgent priority is 0;
1cd179d6 »
2010-03-11 Make this a touch more readable.
134 the least urgent priority is 4,294,967,295.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
135
136 - <delay> is an integer number of seconds to wait before putting the job in
137 the ready queue. The job will be in the "delayed" state during this time.
f568f776 »
2007-12-17 Per-job timeouts. (#1310)
138
139 - <ttr> -- time to run -- is an integer number of seconds to allow a worker
140 to run this job. This time is counted from the moment a worker reserves
141 this job. If the worker does not delete, release, or bury the job within
142 <ttr> seconds, the job will time out and the server will release the job.
35594240 »
2008-02-23 Don't allow jobs with zero ttr.
143 The minimum ttr is 1. If the client sends 0, the server will silently
144 increase the ttr to 1.
5ad4ae71 »
2008-01-02 Remove trailing whitespace.
145
6d0c7cd4 »
2008-04-17 Fix documentation of max job size
146 - <bytes> is an integer indicating the size of the job body, not including the
147 trailing "\r\n". This value must be less than max-job-size (default: 2**16).
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
148
149 - <data> is the job body -- a sequence of bytes of length <bytes> from the
150 previous line.
151
152 After sending the command line and body, the client waits for a reply, which
153 may be:
154
72ec2f80 »
2007-12-17 Return the newly-inserted job id.
155 - "INSERTED <id>\r\n" to indicate success.
156
157 - <id> is the integer id of the new job
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
158
6026eb8e »
2008-02-20 Update code and protocol for dynamic heaps.
159 - "BURIED <id>\r\n" if the server ran out of memory trying to grow the
160 priority queue data structure.
5fca0850 »
2008-02-01 Return buried job id during a put command.
161
162 - <id> is the integer id of the new job
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
163
e95dda4a »
2008-04-16 These responses only apply to the put command.
164 - "EXPECTED_CRLF\r\n" The job body must be followed by a CR-LF pair, that is,
165 "\r\n". These two bytes are not counted in the job size given by the client
166 in the put command line.
167
168 - "JOB_TOO_BIG\r\n" The client has requested to put a job with a body larger
6d0c7cd4 »
2008-04-17 Fix documentation of max job size
169 than max-job-size bytes.
e95dda4a »
2008-04-16 These responses only apply to the put command.
170
182e7fb4 »
2010-03-15 Restrict this error to the put command.
171 - "DRAINING\r\n" This means that the server has been put into "drain mode"
172 and is no longer accepting new jobs. The client should try another server
173 or disconnect and try again later.
174
c1b09c4f »
2008-02-20 Implement tubes.
175 The "use" command is for producers. Subsequent put commands will put jobs into
176 the tube specified by this command. If no use command has been issued, jobs
177 will be put into the tube named "default".
178
179 use <tube>\r\n
180
181 - <tube> is a name at most 200 bytes. It specifies the tube to use. If the
182 tube does not exist, it will be created.
183
184 The only reply is:
185
d6c8814d »
2008-02-27 Fix two errors in doc/protocol.txt.
186 USING <tube>\r\n
187
188 - <tube> is the name of the tube now being used.
c1b09c4f »
2008-02-20 Implement tubes.
189
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
190 Worker Commands
191 ---------------
192
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
193 A process that wants to consume jobs from the queue uses "reserve", "delete",
194 "release", and "bury". The first worker command, "reserve", looks like this:
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
195
196 reserve\r\n
197
209a0d61 »
2008-05-31 Added reserve timeout support.
198 Alternatively, you can specify a timeout as follows:
199
200 reserve-with-timeout <seconds>\r\n
201
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
202 This will return a newly-reserved job. If no job is available to be reserved,
2f24a066 »
2008-03-10 Improve the protocol doc's clarity.
203 beanstalkd will wait to send a response until one becomes available. Once a
204 job is reserved for the client, the client has limited time to run (TTR) the
205 job before the job times out. When the job times out, the server will put the
206 job back into the ready queue. Both the TTR and the actual time left can be
207 found in response to the stats-job command.
208
d8b2d9b0 »
2013-04-13 document unspecified job order within each pri
209 If more than one job is ready, beanstalkd will choose the one with the
8cc3e6b3 »
2013-04-14 correctly document fifo order within each pri
210 smallest priority value. Within each priority, it will choose the one that
211 was received first.
d8b2d9b0 »
2013-04-13 document unspecified job order within each pri
212
209a0d61 »
2008-05-31 Added reserve timeout support.
213 A timeout value of 0 will cause the server to immediately return either a
214 response or TIMED_OUT. A positive value of timeout will limit the amount of
215 time the client will block on the reserve request until a job becomes
216 available.
217
2f24a066 »
2008-03-10 Improve the protocol doc's clarity.
218 During the TTR of a reserved job, the last second is kept by the server as a
219 safety margin, during which the client will not be made to wait for another
220 job. If the client issues a reserve command during the safety margin, or if
221 the safety margin arrives while the client is waiting on a reserve command,
222 the server will respond with:
f96ee87c »
2008-03-07 Reserve timeout, part 1.
223
32c0c88f »
2008-03-10 Change the message name to DEADLINE_SOON.
224 DEADLINE_SOON\r\n
f96ee87c »
2008-03-07 Reserve timeout, part 1.
225
d53c9964 »
2008-03-10 Reserve timeout, part 2.
226 This gives the client a chance to delete or release its reserved job before
227 the server automatically releases it.
228
209a0d61 »
2008-05-31 Added reserve timeout support.
229 TIMED_OUT\r\n
230
231 If a non-negative timeout was specified and the timeout exceeded before a job
c2ee0f36 »
2012-10-18 correctly check for hangup during reserve
232 became available, or if the client's connection is half-closed, the server
233 will respond with TIMED_OUT.
209a0d61 »
2008-05-31 Added reserve timeout support.
234
235 Otherwise, the only other response to this command is a successful reservation
236 in the form of a text line followed by the job body:
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
237
5454b23b »
2008-02-26 Move priority into job stats.
238 RESERVED <id> <bytes>\r\n
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
239 <data>\r\n
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
240
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
241 - <id> is the job id -- an integer unique to this job in this instance of
242 beanstalkd.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
243
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
244 - <bytes> is an integer indicating the size of the job body, not including
245 the trailing "\r\n".
246
247 - <data> is the job body -- a sequence of bytes of length <bytes> from the
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
248 previous line. This is a verbatim copy of the bytes that were originally
249 sent to the server in the put command for this job.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
250
251 The delete command removes a job from the server entirely. It is normally used
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
252 by the client when the job has successfully run to completion. A client can
b5a20491 »
2011-08-10 Delayed jobs are now included in the delete protocol.
253 delete jobs that it has reserved, ready jobs, delayed jobs, and jobs that are
254 buried. The delete command looks like this:
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
255
256 delete <id>\r\n
257
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
258 - <id> is the job id to delete.
259
260 The client then waits for one line of response, which may be:
261
262 - "DELETED\r\n" to indicate success.
263
264 - "NOT_FOUND\r\n" if the job does not exist or is not either reserved by the
84cfd9c5 »
2008-12-01 Update protocol doc -- can now delete ready jobs.
265 client, ready, or buried. This could happen if the job timed out before the
266 client sent the delete command.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
267
268 The release command puts a reserved job back into the ready queue (and marks
269 its state as "ready") to be run by any client. It is normally used when the job
270 fails because of a transitory error. It looks like this:
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
271
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
272 release <id> <pri> <delay>\r\n
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
273
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
274 - <id> is the job id to release.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
275
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
276 - <pri> is a new priority to assign to the job.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
277
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
278 - <delay> is an integer number of seconds to wait before putting the job in
279 the ready queue. The job will be in the "delayed" state during this time.
280
281 The client expects one line of response, which may be:
282
283 - "RELEASED\r\n" to indicate success.
284
6026eb8e »
2008-02-20 Update code and protocol for dynamic heaps.
285 - "BURIED\r\n" if the server ran out of memory trying to grow the priority
286 queue data structure.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
287
288 - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
289
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
290 The bury command puts a job into the "buried" state. Buried jobs are put into a
291 FIFO linked list and will not be touched by the server again until a client
292 kicks them with the "kick" command.
293
294 The bury command looks like this:
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
295
296 bury <id> <pri>\r\n
297
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
298 - <id> is the job id to release.
299
300 - <pri> is a new priority to assign to the job.
301
302 There are two possible responses:
303
304 - "BURIED\r\n" to indicate success.
305
306 - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
10b359ee »
2008-11-18 Documented the touch command.
307
308 The "touch" command allows a worker to request more time to work on a job.
309 This is useful for jobs that potentially take a long time, but you still want
310 the benefits of a TTR pulling a job away from an unresponsive worker. A worker
311 may periodically tell the server that it's still alive and processing a job
157d88bf »
2013-06-21 Document `touch` command's TTR reset
312 (e.g. it may do this on DEADLINE_SOON). The command postpones the auto
313 release of a reserved job until TTR seconds from when the command is issued.
10b359ee »
2008-11-18 Documented the touch command.
314
315 The touch command looks like this:
316
317 touch <id>\r\n
318
319 - <id> is the ID of a job reserved by the current connection.
320
321 There are two possible responses:
322
323 - "TOUCHED\r\n" to indicate success.
324
325 - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
326
c1b09c4f »
2008-02-20 Implement tubes.
327 The "watch" command adds the named tube to the watch list for the current
328 connection. A reserve command will take a job from any of the tubes in the
329 watch list. For each new connection, the watch list initially consists of one
330 tube, named "default".
331
332 watch <tube>\r\n
333
334 - <tube> is a name at most 200 bytes. It specifies a tube to add to the watch
d6c8814d »
2008-02-27 Fix two errors in doc/protocol.txt.
335 list. If the tube doesn't exist, it will be created.
c1b09c4f »
2008-02-20 Implement tubes.
336
337 The reply is:
338
339 WATCHING <count>\r\n
340
341 - <count> is the integer number of tubes currently in the watch list.
342
343 The "ignore" command is for consumers. It removes the named tube from the
344 watch list for the current connection.
345
346 ignore <tube>\r\n
347
348 The reply is one of:
349
350 - "WATCHING <count>\r\n" to indicate success.
351
352 - <count> is the integer number of tubes currently in the watch list.
353
354 - "NOT_IGNORED\r\n" if the client attempts to ignore the only tube in its
355 watch list.
356
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
357 Other Commands
358 --------------
359
360fdc04 »
2008-04-09 New peek commands.
360 The peek commands let the client inspect a job in the system. There are four
361 variations. All but the first operate only on the currently used tube.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
362
360fdc04 »
2008-04-09 New peek commands.
363 - "peek <id>\r\n" - return job <id>.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
364
360fdc04 »
2008-04-09 New peek commands.
365 - "peek-ready\r\n" - return the next ready job.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
366
360fdc04 »
2008-04-09 New peek commands.
367 - "peek-delayed\r\n" - return the delayed job with the shortest delay left.
368
369 - "peek-buried\r\n" - return the next job in the list of buried jobs.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
370
371 There are two possible responses, either a single line:
372
360fdc04 »
2008-04-09 New peek commands.
373 - "NOT_FOUND\r\n" if the requested job doesn't exist or there are no jobs in
374 the requested state.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
375
376 Or a line followed by a chunk of data, if the command was successful:
377
5454b23b »
2008-02-26 Move priority into job stats.
378 FOUND <id> <bytes>\r\n
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
379 <data>\r\n
380
381 - <id> is the job id.
382
383 - <bytes> is an integer indicating the size of the job body, not including
384 the trailing "\r\n".
385
386 - <data> is the job body -- a sequence of bytes of length <bytes> from the
387 previous line.
388
df46041a »
2008-04-09 Per-tube delay queue.
389 The kick command applies only to the currently used tube. It moves jobs into
390 the ready queue. If there are any buried jobs, it will only kick buried jobs.
391 Otherwise it will kick delayed jobs. It looks like:
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
392
ca1c4e61 »
2008-02-27 Make kick just use the current tube.
393 kick <bound>\r\n
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
394
395 - <bound> is an integer upper bound on the number of jobs to kick. The server
b46f1a77 »
2007-12-10 More protocol documentation plus README and TODO.
396 will kick no more than <bound> jobs.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
397
ca1c4e61 »
2008-02-27 Make kick just use the current tube.
398 The response is of the form:
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
399
400 KICKED <count>\r\n
401
402 - <count> is an integer indicating the number of jobs actually kicked.
403
c47144f9 »
2012-09-13 Update the protocol documentation.
404 The kick-job command is a variant of kick that operates with a single job
405 identified by its job id. If the given job id exists and is in a buried or
406 delayed state, it will be moved to the ready queue of the the same tube where it
407 currently belongs. The syntax is:
408
409 kick-job <id>\r\n
410
411 - <id> is the job id to kick.
412
413 The response is one of:
414
415 - "NOT_FOUND\r\n" if the job does not exist or is not in a kickable state. This
416 can also happen upon internal errors.
417
418 - "KICKED\r\n" when the operation succeeded.
419
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
420 The stats-job command gives statistical information about the specified job if
421 it exists. Its form is:
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
422
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
423 stats-job <id>\r\n
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
424
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
425 - <id> is a job id.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
426
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
427 The response is one of:
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
428
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
429 - "NOT_FOUND\r\n" if the job does not exist.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
430
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
431 - "OK <bytes>\r\n<data>\r\n"
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
432
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
433 - <bytes> is the size of the following data section in bytes.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
434
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
435 - <data> is a sequence of bytes of length <bytes> from the previous line. It
436 is a YAML file with statistical information represented a dictionary.
437
438 The stats-job data is a YAML file representing a single dictionary of strings
439 to scalars. It contains these keys:
440
441 - "id" is the job id
442
443 - "tube" is the name of the tube that contains this job
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
444
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
445 - "state" is "ready" or "delayed" or "reserved" or "buried"
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
446
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
447 - "pri" is the priority value set by the put, release, or bury commands.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
448
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
449 - "age" is the time in seconds since the put command that created this job.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
450
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
451 - "time-left" is the number of seconds left until the server puts this job
452 into the ready queue. This number is only meaningful if the job is
453 reserved or delayed. If the job is reserved and this amount of time
454 elapses before its state changes, it is considered to have timed out.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
455
dcf624d4 »
2011-12-03 add file index to job stats
456 - "file" is the number of the earliest binlog file containing this job.
457 If -b wasn't used, this will be 0.
458
fdd7693d »
2009-06-18 add 'reserves' counter per job
459 - "reserves" is the number of times this job has been reserved.
460
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
461 - "timeouts" is the number of times this job has timed out during a
462 reservation.
c1b09c4f »
2008-02-20 Implement tubes.
463
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
464 - "releases" is the number of times a client has released this job from a
465 reservation.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
466
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
467 - "buries" is the number of times this job has been buried.
5454b23b »
2008-02-26 Move priority into job stats.
468
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
469 - "kicks" is the number of times this job has been kicked.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
470
7c451fb1 »
2008-02-26 Implement per-tube statistics.
471 The stats-tube command gives statistical information about the specified tube
472 if it exists. Its form is:
473
474 stats-tube <tube>\r\n
475
476 - <tube> is a name at most 200 bytes. Stats will be returned for this tube.
477
478 The response is one of:
479
480 - "NOT_FOUND\r\n" if the tube does not exist.
481
482 - "OK <bytes>\r\n<data>\r\n"
483
484 - <bytes> is the size of the following data section in bytes.
485
486 - <data> is a sequence of bytes of length <bytes> from the previous line. It
487 is a YAML file with statistical information represented a dictionary.
488
489 The stats-tube data is a YAML file representing a single dictionary of strings
490 to scalars. It contains these keys:
491
492 - "name" is the tube's name.
493
494 - "current-jobs-urgent" is the number of ready jobs with priority < 1024 in
495 this tube.
496
497 - "current-jobs-ready" is the number of jobs in the ready queue in this tube.
498
499 - "current-jobs-reserved" is the number of jobs reserved by all clients in
500 this tube.
501
df46041a »
2008-04-09 Per-tube delay queue.
502 - "current-jobs-delayed" is the number of delayed jobs in this tube.
503
7c451fb1 »
2008-02-26 Implement per-tube statistics.
504 - "current-jobs-buried" is the number of buried jobs in this tube.
505
e50ec077 »
2011-11-02 clarify behavior of cumulative stats; closes #81
506 - "total-jobs" is the cumulative count of jobs created in this tube in
507 the current beanstalkd process.
7c451fb1 »
2008-02-26 Implement per-tube statistics.
508
cb0f3d30 »
2012-09-11 document missing tube stats fields; fixes #127
509 - "current-using" is the number of open connections that are currently
510 using this tube.
511
7c451fb1 »
2008-02-26 Implement per-tube statistics.
512 - "current-waiting" is the number of open connections that have issued a
513 reserve command while watching this tube but not yet received a response.
514
cb0f3d30 »
2012-09-11 document missing tube stats fields; fixes #127
515 - "current-watching" is the number of open connections that are currently
516 watching this tube.
517
5fa2e8ae »
2009-11-05 Update documentation.
518 - "pause" is the number of seconds the tube has been paused for.
d5d311d0 »
2009-11-04 Add pause-tube command
519
772033f6 »
2011-10-03 adding support for counting deletes on a tube
520 - "cmd-delete" is the cumulative number of delete commands for this tube
521
5fa2e8ae »
2009-11-05 Update documentation.
522 - "cmd-pause-tube" is the cumulative number of pause-tube commands for this
523 tube.
524
525 - "pause-time-left" is the number of seconds until the tube is un-paused.
d5d311d0 »
2009-11-04 Add pause-tube command
526
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
527 The stats command gives statistical information about the system as a whole.
528 Its form is:
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
529
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
530 stats\r\n
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
531
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
532 The server will respond:
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
533
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
534 OK <bytes>\r\n
535 <data>\r\n
536
537 - <bytes> is the size of the following data section in bytes.
538
539 - <data> is a sequence of bytes of length <bytes> from the previous line. It
540 is a YAML file with statistical information represented a dictionary.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
541
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
542 The stats data for the system is a YAML file representing a single dictionary
e50ec077 »
2011-11-02 clarify behavior of cumulative stats; closes #81
543 of strings to scalars. Entries described as "cumulative" are reset when the
544 beanstalkd process starts; they are not stored on disk with the -b flag.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
545
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
546 - "current-jobs-urgent" is the number of ready jobs with priority < 1024.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
547
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
548 - "current-jobs-ready" is the number of jobs in the ready queue.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
549
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
550 - "current-jobs-reserved" is the number of jobs reserved by all clients.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
551
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
552 - "current-jobs-delayed" is the number of delayed jobs.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
553
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
554 - "current-jobs-buried" is the number of buried jobs.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
555
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
556 - "cmd-put" is the cumulative number of put commands.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
557
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
558 - "cmd-peek" is the cumulative number of peek commands.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
559
b8545431 »
2008-04-16 Count all four peek commands separately.
560 - "cmd-peek-ready" is the cumulative number of peek-ready commands.
561
562 - "cmd-peek-delayed" is the cumulative number of peek-delayed commands.
563
564 - "cmd-peek-buried" is the cumulative number of peek-buried commands.
565
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
566 - "cmd-reserve" is the cumulative number of reserve commands.
3d9a8ad9 »
2007-12-04 Update and reformat the protocol doc.
567
1c27cefd »
2008-02-27 Add a list-tube-used command and missing stats.
568 - "cmd-use" is the cumulative number of use commands.
569
570 - "cmd-watch" is the cumulative number of watch commands.
571
572 - "cmd-ignore" is the cumulative number of ignore commands.
573
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
574 - "cmd-delete" is the cumulative number of delete commands.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
575
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
576 - "cmd-release" is the cumulative number of release commands.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
577
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
578 - "cmd-bury" is the cumulative number of bury commands.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
579
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
580 - "cmd-kick" is the cumulative number of kick commands.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
581
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
582 - "cmd-stats" is the cumulative number of stats commands.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
583
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
584 - "cmd-stats-job" is the cumulative number of stats-job commands.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
585
7c451fb1 »
2008-02-26 Implement per-tube statistics.
586 - "cmd-stats-tube" is the cumulative number of stats-tube commands.
587
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
588 - "cmd-list-tubes" is the cumulative number of list-tubes commands.
1d91d7aa »
2008-02-26 Implement the list-tubes command.
589
1c27cefd »
2008-02-27 Add a list-tube-used command and missing stats.
590 - "cmd-list-tube-used" is the cumulative number of list-tube-used commands.
591
d77875dc »
2008-02-26 More consistent command naming.
592 - "cmd-list-tubes-watched" is the cumulative number of list-tubes-watched
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
593 commands.
e8975461 »
2008-02-26 Implement list-watched-tubes command.
594
76adfd9e »
2013-03-18 don't over-specify the format of stats id field
595 - "cmd-pause-tube" is the cumulative number of pause-tube commands.
d5d311d0 »
2009-11-04 Add pause-tube command
596
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
597 - "job-timeouts" is the cumulative count of times a job has timed out.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
598
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
599 - "total-jobs" is the cumulative count of jobs created.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
600
64c62412 »
2008-03-25 Add max job size option and stats entry.
601 - "max-job-size" is the maximum number of bytes in a job.
602
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
603 - "current-tubes" is the number of currently-existing tubes.
c1b09c4f »
2008-02-20 Implement tubes.
604
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
605 - "current-connections" is the number of currently open connections.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
606
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
607 - "current-producers" is the number of open connections that have each
608 issued at least one put command.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
609
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
610 - "current-workers" is the number of open connections that have each issued
611 at least one reserve command.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
612
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
613 - "current-waiting" is the number of open connections that have issued a
614 reserve command but not yet received a response.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
615
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
616 - "total-connections" is the cumulative count of connections.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
617
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
618 - "pid" is the process id of the server.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
619
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
620 - "version" is the version string of the server.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
621
e50ec077 »
2011-11-02 clarify behavior of cumulative stats; closes #81
622 - "rusage-utime" is the cumulative user CPU time of this process in seconds
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
623 and microseconds.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
624
e50ec077 »
2011-11-02 clarify behavior of cumulative stats; closes #81
625 - "rusage-stime" is the cumulative system CPU time of this process in
4ab29620 »
2008-02-26 Split job stats into its own command: stats-job.
626 seconds and microseconds.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
627
e50ec077 »
2011-11-02 clarify behavior of cumulative stats; closes #81
628 - "uptime" is the number of seconds since this server process started running.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
629
90d3ab88 »
2008-11-28 Add some binlog detail to the stats command
630 - "binlog-oldest-index" is the index of the oldest binlog file needed to
76adfd9e »
2013-03-18 don't over-specify the format of stats id field
631 store the current jobs.
90d3ab88 »
2008-11-28 Add some binlog detail to the stats command
632
633 - "binlog-current-index" is the index of the current binlog file being
76adfd9e »
2013-03-18 don't over-specify the format of stats id field
634 written to. If binlog is not active this value will be 0.
90d3ab88 »
2008-11-28 Add some binlog detail to the stats command
635
636 - "binlog-max-size" is the maximum size in bytes a binlog file is allowed
76adfd9e »
2013-03-18 don't over-specify the format of stats id field
637 to get before a new binlog file is opened.
90d3ab88 »
2008-11-28 Add some binlog detail to the stats command
638
fe9cc6c8 »
2011-05-15 document the new binlog stats
639 - "binlog-records-written" is the cumulative number of records written
76adfd9e »
2013-03-18 don't over-specify the format of stats id field
640 to the binlog.
fe9cc6c8 »
2011-05-15 document the new binlog stats
641
642 - "binlog-records-migrated" is the cumulative number of records written
76adfd9e »
2013-03-18 don't over-specify the format of stats id field
643 as part of compaction.
fe9cc6c8 »
2011-05-15 document the new binlog stats
644
76adfd9e »
2013-03-18 don't over-specify the format of stats id field
645 - "id" is a random id string for this server process, generated when each
646 beanstalkd process starts.
d5ffd665 »
2012-12-04 Add id and hostname to server stats.
647
76adfd9e »
2013-03-18 don't over-specify the format of stats id field
648 - "hostname" the hostname of the machine as determined by uname.
d5ffd665 »
2012-12-04 Add id and hostname to server stats.
649
e8975461 »
2008-02-26 Implement list-watched-tubes command.
650 The list-tubes command returns a list of all existing tubes. Its form is:
1d91d7aa »
2008-02-26 Implement the list-tubes command.
651
652 list-tubes\r\n
653
654 The response is:
655
656 OK <bytes>\r\n
657 <data>\r\n
658
659 - <bytes> is the size of the following data section in bytes.
660
661 - <data> is a sequence of bytes of length <bytes> from the previous line. It
e8975461 »
2008-02-26 Implement list-watched-tubes command.
662 is a YAML file containing all tube names as a list of strings.
663
1c27cefd »
2008-02-27 Add a list-tube-used command and missing stats.
664 The list-tube-used command returns the tube currently being used by the
665 client. Its form is:
666
667 list-tube-used\r\n
668
669 The response is:
670
671 USING <tube>\r\n
672
673 - <tube> is the name of the tube being used.
674
d77875dc »
2008-02-26 More consistent command naming.
675 The list-tubes-watched command returns a list tubes currently being watched by
e8975461 »
2008-02-26 Implement list-watched-tubes command.
676 the client. Its form is:
677
d77875dc »
2008-02-26 More consistent command naming.
678 list-tubes-watched\r\n
e8975461 »
2008-02-26 Implement list-watched-tubes command.
679
680 The response is:
681
682 OK <bytes>\r\n
683 <data>\r\n
684
685 - <bytes> is the size of the following data section in bytes.
686
687 - <data> is a sequence of bytes of length <bytes> from the previous line. It
688 is a YAML file containing watched tube names as a list of strings.
ff64dbf1 »
2007-11-27 Paste in protocol documentation from the wiki.
689
e21bc142 »
2009-05-27 Add quit to protocol docs.
690 The quit command simply closes the connection. Its form is:
691
692 quit\r\n
d5d311d0 »
2009-11-04 Add pause-tube command
693
694 The pause-tube command can delay any new job being reserved for a given time. Its form is:
695
696 pause-tube <tube-name> <delay>\r\n
697
698 - <tube> is the tube to pause
699
700 - <delay> is an integer number of seconds to wait before reserving any more
701 jobs from the queue
702
703 There are two possible responses:
704
705 - "PAUSED\r\n" to indicate success.
706
707 - "NOT_FOUND\r\n" if the tube does not exist.
708
Something went wrong with that request. Please try again.