1Protocol 2-------- 3 4Clients of memcached communicate with server through TCP connections. 5(A UDP interface is also available; details are below under "UDP 6protocol.") A given running memcached server listens on some 7(configurable) port; clients connect to that port, send commands to 8the server, read responses, and eventually close the connection. 9 10There is no need to send any command to end the session. A client may 11just close the connection at any moment it no longer needs it. Note, 12however, that clients are encouraged to cache their connections rather 13than reopen them every time they need to store or retrieve data. This 14is because memcached is especially designed to work very efficiently 15with a very large number (many hundreds, more than a thousand if 16necessary) of open connections. Caching connections will eliminate the 17overhead associated with establishing a TCP connection (the overhead 18of preparing for a new connection on the server side is insignificant 19compared to this). 20 21There are two kinds of data sent in the memcache protocol: text lines 22and unstructured data. Text lines are used for commands from clients 23and responses from servers. Unstructured data is sent when a client 24wants to store or retrieve data. The server will transmit back 25unstructured data in exactly the same way it received it, as a byte 26stream. The server doesn't care about byte order issues in 27unstructured data and isn't aware of them. There are no limitations on 28characters that may appear in unstructured data; however, the reader 29of such data (either a client or a server) will always know, from a 30preceding text line, the exact length of the data block being 31transmitted. 32 33Text lines are always terminated by \r\n. Unstructured data is _also_ 34terminated by \r\n, even though \r, \n or any other 8-bit characters 35may also appear inside the data. Therefore, when a client retrieves 36data from a server, it must use the length of the data block (which it 37will be provided with) to determine where the data block ends, and not 38the fact that \r\n follows the end of the data block, even though it 39does. 40 41Keys 42---- 43 44Data stored by memcached is identified with the help of a key. A key 45is a text string which should uniquely identify the data for clients 46that are interested in storing and retrieving it. Currently the 47length limit of a key is set at 250 characters (of course, normally 48clients wouldn't need to use such long keys); the key must not include 49control characters or whitespace. 50 51Commands 52-------- 53 54There are three types of commands. 55 56Storage commands (there are six: "set", "add", "replace", "append" 57"prepend" and "cas") ask the server to store some data identified by a 58key. The client sends a command line, and then a data block; after 59that the client expects one line of response, which will indicate 60success or failure. 61 62Retrieval commands (there are two: "get" and "gets") ask the server to 63retrieve data corresponding to a set of keys (one or more keys in one 64request). The client sends a command line, which includes all the 65requested keys; after that for each item the server finds it sends to 66the client one response line with information about the item, and one 67data block with the item's data; this continues until the server 68finished with the "END" response line. 69 70All other commands don't involve unstructured data. In all of them, 71the client sends one command line, and expects (depending on the 72command) either one line of response, or several lines of response 73ending with "END" on the last line. 74 75A command line always starts with the name of the command, followed by 76parameters (if any) delimited by whitespace. Command names are 77lower-case and are case-sensitive. 78 79Expiration times 80---------------- 81 82Some commands involve a client sending some kind of expiration time 83(relative to an item or to an operation requested by the client) to 84the server. In all such cases, the actual value sent may either be 85Unix time (number of seconds since January 1, 1970, as a 32-bit 86value), or a number of seconds starting from current time. In the 87latter case, this number of seconds may not exceed 60*60*24*30 (number 88of seconds in 30 days); if the number sent by a client is larger than 89that, the server will consider it to be real Unix time value rather 90than an offset from current time. 91 92 93Error strings 94------------- 95 96Each command sent by a client may be answered with an error string 97from the server. These error strings come in three types: 98 99- "ERROR\r\n" 100 101 means the client sent a nonexistent command name. 102 103- "CLIENT_ERROR <error>\r\n" 104 105 means some sort of client error in the input line, i.e. the input 106 doesn't conform to the protocol in some way. <error> is a 107 human-readable error string. 108 109- "SERVER_ERROR <error>\r\n" 110 111 means some sort of server error prevents the server from carrying 112 out the command. <error> is a human-readable error string. In cases 113 of severe server errors, which make it impossible to continue 114 serving the client (this shouldn't normally happen), the server will 115 close the connection after sending the error line. This is the only 116 case in which the server closes a connection to a client. 117 118 119In the descriptions of individual commands below, these error lines 120are not again specifically mentioned, but clients must allow for their 121possibility. 122 123 124Storage commands 125---------------- 126 127First, the client sends a command line which looks like this: 128 129<command name> <key> <flags> <exptime> <bytes> [noreply]\r\n 130cas <key> <flags> <exptime> <bytes> <cas unique> [noreply]\r\n 131 132- <command name> is "set", "add", "replace", "append" or "prepend" 133 134 "set" means "store this data". 135 136 "add" means "store this data, but only if the server *doesn't* already 137 hold data for this key". 138 139 "replace" means "store this data, but only if the server *does* 140 already hold data for this key". 141 142 "append" means "add this data to an existing key after existing data". 143 144 "prepend" means "add this data to an existing key before existing data". 145 146 The append and prepend commands do not accept flags or exptime. 147 They update existing data portions, and ignore new flag and exptime 148 settings. 149 150 "cas" is a check and set operation which means "store this data but 151 only if no one else has updated since I last fetched it." 152 153- <key> is the key under which the client asks to store the data 154 155- <flags> is an arbitrary 16-bit unsigned integer (written out in 156 decimal) that the server stores along with the data and sends back 157 when the item is retrieved. Clients may use this as a bit field to 158 store data-specific information; this field is opaque to the server. 159 Note that in memcached 1.2.1 and higher, flags may be 32-bits, instead 160 of 16, but you might want to restrict yourself to 16 bits for 161 compatibility with older versions. 162 163- <exptime> is expiration time. If it's 0, the item never expires 164 (although it may be deleted from the cache to make place for other 165 items). If it's non-zero (either Unix time or offset in seconds from 166 current time), it is guaranteed that clients will not be able to 167 retrieve this item after the expiration time arrives (measured by 168 server time). If a negative value is given the item is immediately 169 expired. 170 171- <bytes> is the number of bytes in the data block to follow, *not* 172 including the delimiting \r\n. <bytes> may be zero (in which case 173 it's followed by an empty data block). 174 175- <cas unique> is a unique 64-bit value of an existing entry. 176 Clients should use the value returned from the "gets" command 177 when issuing "cas" updates. 178 179- "noreply" optional parameter instructs the server to not send the 180 reply. NOTE: if the request line is malformed, the server can't 181 parse "noreply" option reliably. In this case it may send the error 182 to the client, and not reading it on the client side will break 183 things. Client should construct only valid requests. 184 185After this line, the client sends the data block: 186 187<data block>\r\n 188 189- <data block> is a chunk of arbitrary 8-bit data of length <bytes> 190 from the previous line. 191 192After sending the command line and the data block the client awaits 193the reply, which may be: 194 195- "STORED\r\n", to indicate success. 196 197- "NOT_STORED\r\n" to indicate the data was not stored, but not 198because of an error. This normally means that the 199condition for an "add" or a "replace" command wasn't met. 200 201- "EXISTS\r\n" to indicate that the item you are trying to store with 202a "cas" command has been modified since you last fetched it. 203 204- "NOT_FOUND\r\n" to indicate that the item you are trying to store 205with a "cas" command did not exist. 206 207 208Retrieval command: 209------------------ 210 211The retrieval commands "get" and "gets" operates like this: 212 213get <key>*\r\n 214gets <key>*\r\n 215 216- <key>* means one or more key strings separated by whitespace. 217 218After this command, the client expects zero or more items, each of 219which is received as a text line followed by a data block. After all 220the items have been transmitted, the server sends the string 221 222"END\r\n" 223 224to indicate the end of response. 225 226Each item sent by the server looks like this: 227 228VALUE <key> <flags> <bytes> [<cas unique>]\r\n 229<data block>\r\n 230 231- <key> is the key for the item being sent 232 233- <flags> is the flags value set by the storage command 234 235- <bytes> is the length of the data block to follow, *not* including 236 its delimiting \r\n 237 238- <cas unique> is a unique 64-bit integer that uniquely identifies 239 this specific item. 240 241- <data block> is the data for this item. 242 243If some of the keys appearing in a retrieval request are not sent back 244by the server in the item list this means that the server does not 245hold items with such keys (because they were never stored, or stored 246but deleted to make space for more items, or expired, or explicitly 247deleted by a client). 248 249 250Deletion 251-------- 252 253The command "delete" allows for explicit deletion of items: 254 255delete <key> [noreply]\r\n 256 257- <key> is the key of the item the client wishes the server to delete 258 259- "noreply" optional parameter instructs the server to not send the 260 reply. See the note in Storage commands regarding malformed 261 requests. 262 263The response line to this command can be one of: 264 265- "DELETED\r\n" to indicate success 266 267- "NOT_FOUND\r\n" to indicate that the item with this key was not 268 found. 269 270See the "flush_all" command below for immediate invalidation 271of all existing items. 272 273 274Increment/Decrement 275------------------- 276 277Commands "incr" and "decr" are used to change data for some item 278in-place, incrementing or decrementing it. The data for the item is 279treated as decimal representation of a 64-bit unsigned integer. If 280the current data value does not conform to such a representation, the 281incr/decr commands return an error (memcached <= 1.2.6 treated the 282bogus value as if it were 0, leading to confusion). Also, the item 283must already exist for incr/decr to work; these commands won't pretend 284that a non-existent key exists with value 0; instead, they will fail. 285 286The client sends the command line: 287 288incr <key> <value> [noreply]\r\n 289 290or 291 292decr <key> <value> [noreply]\r\n 293 294- <key> is the key of the item the client wishes to change 295 296- <value> is the amount by which the client wants to increase/decrease 297the item. It is a decimal representation of a 64-bit unsigned integer. 298 299- "noreply" optional parameter instructs the server to not send the 300 reply. See the note in Storage commands regarding malformed 301 requests. 302 303The response will be one of: 304 305- "NOT_FOUND\r\n" to indicate the item with this value was not found 306 307- <value>\r\n , where <value> is the new value of the item's data, 308 after the increment/decrement operation was carried out. 309 310Note that underflow in the "decr" command is caught: if a client tries 311to decrease the value below 0, the new value will be 0. Overflow in 312the "incr" command will wrap around the 64 bit mark. 313 314Note also that decrementing a number such that it loses length isn't 315guaranteed to decrement its returned length. The number MAY be 316space-padded at the end, but this is purely an implementation 317optimization, so you also shouldn't rely on that. 318 319Touch 320----- 321 322The "touch" command is used to update the expiration time of an existing item 323without fetching it. 324 325touch <key> <exptime> [noreply]\r\n 326 327- <key> is the key of the item the client wishes the server to touch 328 329- <exptime> is expiration time. Works the same as with the update commands 330 (set/add/etc). This replaces the existing expiration time. If an existing 331 item were to expire in 10 seconds, but then was touched with an 332 expiration time of "20", the item would then expire in 20 seconds. 333 334- "noreply" optional parameter instructs the server to not send the 335 reply. See the note in Storage commands regarding malformed 336 requests. 337 338The response line to this command can be one of: 339 340- "TOUCHED\r\n" to indicate success 341 342- "NOT_FOUND\r\n" to indicate that the item with this key was not 343 found. 344 345Slabs Reassign 346-------------- 347 348NOTE: This command is subject to change as of this writing. 349 350The slabs reassign command is used to redistribute memory once a running 351instance has hit its limit. It might be desirable to have memory laid out 352differently than was automatically assigned after the server started. 353 354slabs reassign <source class> <dest class>\r\n 355 356- <source class> is an id number for the slab class to steal a page from 357 358A source class id of -1 means "pick from any valid class" 359 360- <dest class> is an id number for the slab class to move a page to 361 362The response line could be one of: 363 364- "OK" to indicate the page has been scheduled to move 365 366- "BUSY [message]" to indicate a page is already being processed, try again 367 later. 368 369- "BADCLASS [message]" a bad class id was specified 370 371- "NOSPARE [message]" source class has no spare pages 372 373- "NOTFULL [message]" dest class must be full to move new pages to it 374 375- "UNSAFE [message]" source class cannot move a page right now 376 377- "SAME [message]" must specify different source/dest ids. 378 379Slabs Automove 380-------------- 381 382NOTE: This command is subject to change as of this writing. 383 384The slabs automove command enables a background thread which decides on its 385own when to move memory between slab classes. Its implementation and options 386will likely be in flux for several versions. See the wiki/mailing list for 387more details. 388 389The automover can be enabled or disabled at runtime with this command. 390 391slabs automove <0|1> 392 393- 0|1|2 is the indicator on whether to enable the slabs automover or not. 394 395The response should always be "OK\r\n" 396 397- <0> means to set the thread on standby 398 399- <1> means to return pages to a global pool when there are more than 2 pages 400 worth of free chunks in a slab class. Pages are then re-assigned back into 401 other classes as-needed. 402 403- <2> is a highly aggressive mode which causes pages to be moved every time 404 there is an eviction. It is not recommended to run for very long in this 405 mode unless your access patterns are very well understood. 406 407LRU_Crawler 408----------- 409 410NOTE: This command (and related commands) are subject to change as of this 411writing. 412 413The LRU Crawler is an optional background thread which will walk from the tail 414toward the head of requested slab classes, actively freeing memory for expired 415items. This is useful if you have a mix of items with both long and short 416TTL's, but aren't accessed very often. This system is not required for normal 417usage, and can add small amounts of latency and increase CPU usage. 418 419lru_crawler <enable|disable> 420 421- Enable or disable the LRU Crawler background thread. 422 423The response line could be one of: 424 425- "OK" to indicate the crawler has been started or stopped. 426 427- "ERROR [message]" something went wrong while enabling or disabling. 428 429lru_crawler sleep <microseconds> 430 431- The number of microseconds to sleep in between each item checked for 432 expiration. Smaller numbers will obviously impact the system more. 433 A value of "0" disables the sleep, "1000000" (one second) is the max. 434 435The response line could be one of: 436 437- "OK" 438 439- "CLIENT_ERROR [message]" indicating a format or bounds issue. 440 441lru_crawler tocrawl <32u> 442 443- The maximum number of items to inspect in a slab class per run request. This 444 allows you to avoid scanning all of very large slabs when it is unlikely to 445 find items to expire. 446 447The response line could be one of: 448 449- "OK" 450 451- "CLIENT_ERROR [message]" indicating a format or bound issue. 452 453lru_crawler crawl <classid,classid,classid|all> 454 455- Takes a single, or a list of, numeric classids (ie: 1,3,10). This instructs 456 the crawler to start at the tail of each of these classids and run to the 457 head. The crawler cannot be stopped or restarted until it completes the 458 previous request. 459 460 The special keyword "all" instructs it to crawl all slabs with items in 461 them. 462 463The response line could be one of: 464 465- "OK" to indicate successful launch. 466 467- "BUSY [message]" to indicate the crawler is already processing a request. 468 469- "BADCLASS [message]" to indicate an invalid class was specified. 470 471Watchers 472-------- 473 474Watchers are a way to connect to memcached and inspect what's going on 475internally. This is an evolving feature so new endpoints should show up over 476time. 477 478watch <fetchers|mutations|evictions> 479 480- Turn connection into a watcher. Options can be stacked and are 481 space-separated. Logs will be sent to the watcher until it disconnects. 482 483The response line could be one of: 484 485- "OK" to indicate the watcher is ready to send logs. 486 487- "ERROR [message]" something went wrong while enabling. 488 489The response format is in "key=value key2=value2" format, for easy parsing. 490Lines are prepending with "ts=" for a timestamp and "gid=" for a global ID 491number of the log line. Given how logs are collected internally they may be 492printed out of order. If this is important the GID may be used to put log 493lines back in order. 494 495The value of keys (and potentially other things) are "URI encoded". Since most 496keys used conform to standard ASCII, this should have no effect. For keys with 497less standard or binary characters, "%NN"'s are inserted to represent the 498byte, ie: "n%2Cfoo" for "n,foo". 499 500The arguments are: 501 502- "fetchers": Currently emits logs every time an item is fetched internally. 503 This means a "set" command would also emit an item_get log, as it checks for 504 an item before replacing it. Multigets should also emit multiple lines. 505 506- "mutations": Currently emits logs when an item is stored in most cases. 507 Shows errors for most cases when items cannot be stored. 508 509- "evictions": Shows some information about items as they are evicted from the 510 cache. Useful in seeing if items being evicted were actually used, and which 511 keys are getting removed. 512 513Statistics 514---------- 515 516The command "stats" is used to query the server about statistics it 517maintains and other internal data. It has two forms. Without 518arguments: 519 520stats\r\n 521 522it causes the server to output general-purpose statistics and 523settings, documented below. In the other form it has some arguments: 524 525stats <args>\r\n 526 527Depending on <args>, various internal data is sent by the server. The 528kinds of arguments and the data sent are not documented in this version 529of the protocol, and are subject to change for the convenience of 530memcache developers. 531 532 533General-purpose statistics 534-------------------------- 535 536Upon receiving the "stats" command without arguments, the server sents 537a number of lines which look like this: 538 539STAT <name> <value>\r\n 540 541The server terminates this list with the line 542 543END\r\n 544 545In each line of statistics, <name> is the name of this statistic, and 546<value> is the data. The following is the list of all names sent in 547response to the "stats" command, together with the type of the value 548sent for this name, and the meaning of the value. 549 550In the type column below, "32u" means a 32-bit unsigned integer, "64u" 551means a 64-bit unsigned integer. '32u.32u' means two 32-bit unsigned 552integers separated by a colon (treat this as a floating point number). 553 554|-----------------------+---------+-------------------------------------------| 555| Name | Type | Meaning | 556|-----------------------+---------+-------------------------------------------| 557| pid | 32u | Process id of this server process | 558| uptime | 32u | Number of secs since the server started | 559| time | 32u | current UNIX time according to the server | 560| version | string | Version string of this server | 561| pointer_size | 32 | Default size of pointers on the host OS | 562| | | (generally 32 or 64) | 563| rusage_user | 32u.32u | Accumulated user time for this process | 564| | | (seconds:microseconds) | 565| rusage_system | 32u.32u | Accumulated system time for this process | 566| | | (seconds:microseconds) | 567| curr_items | 64u | Current number of items stored | 568| total_items | 64u | Total number of items stored since | 569| | | the server started | 570| bytes | 64u | Current number of bytes used | 571| | | to store items | 572| curr_connections | 32u | Number of open connections | 573| total_connections | 32u | Total number of connections opened since | 574| | | the server started running | 575| rejected_connections | 64u | Conns rejected in maxconns_fast mode | 576| connection_structures | 32u | Number of connection structures allocated | 577| | | by the server | 578| reserved_fds | 32u | Number of misc fds used internally | 579| cmd_get | 64u | Cumulative number of retrieval reqs | 580| cmd_set | 64u | Cumulative number of storage reqs | 581| cmd_flush | 64u | Cumulative number of flush reqs | 582| cmd_touch | 64u | Cumulative number of touch reqs | 583| get_hits | 64u | Number of keys that have been requested | 584| | | and found present | 585| get_misses | 64u | Number of items that have been requested | 586| | | and not found | 587| get_expired | 64u | Number of items that have been requested | 588| | | but had already expired. | 589| get_flushed | 64u | Number of items that have been requested | 590| | | but have been flushed via flush_all | 591| delete_misses | 64u | Number of deletions reqs for missing keys | 592| delete_hits | 64u | Number of deletion reqs resulting in | 593| | | an item being removed. | 594| incr_misses | 64u | Number of incr reqs against missing keys. | 595| incr_hits | 64u | Number of successful incr reqs. | 596| decr_misses | 64u | Number of decr reqs against missing keys. | 597| decr_hits | 64u | Number of successful decr reqs. | 598| cas_misses | 64u | Number of CAS reqs against missing keys. | 599| cas_hits | 64u | Number of successful CAS reqs. | 600| cas_badval | 64u | Number of CAS reqs for which a key was | 601| | | found, but the CAS value did not match. | 602| touch_hits | 64u | Numer of keys that have been touched with | 603| | | a new expiration time | 604| touch_misses | 64u | Numer of items that have been touched and | 605| | | not found | 606| auth_cmds | 64u | Number of authentication commands | 607| | | handled, success or failure. | 608| auth_errors | 64u | Number of failed authentications. | 609| idle_kicks | 64u | Number of connections closed due to | 610| | | reaching their idle timeout. | 611| evictions | 64u | Number of valid items removed from cache | 612| | | to free memory for new items | 613| reclaimed | 64u | Number of times an entry was stored using | 614| | | memory from an expired entry | 615| bytes_read | 64u | Total number of bytes read by this server | 616| | | from network | 617| bytes_written | 64u | Total number of bytes sent by this server | 618| | | to network | 619| limit_maxbytes | size_t | Number of bytes this server is allowed to | 620| | | use for storage. | 621| accepting_conns | bool | Whether or not server is accepting conns | 622| listen_disabled_num | 64u | Number of times server has stopped | 623| | | accepting new connections (maxconns). | 624| time_in_listen_disabled_us | 625| | 64u | Number of microseconds in maxconns. | 626| threads | 32u | Number of worker threads requested. | 627| | | (see doc/threads.txt) | 628| conn_yields | 64u | Number of times any connection yielded to | 629| | | another due to hitting the -R limit. | 630| hash_power_level | 32u | Current size multiplier for hash table | 631| hash_bytes | 64u | Bytes currently used by hash tables | 632| hash_is_expanding | bool | Indicates if the hash table is being | 633| | | grown to a new size | 634| expired_unfetched | 64u | Items pulled from LRU that were never | 635| | | touched by get/incr/append/etc before | 636| | | expiring | 637| evicted_unfetched | 64u | Items evicted from LRU that were never | 638| | | touched by get/incr/append/etc. | 639| slab_reassign_running | bool | If a slab page is being moved | 640| slabs_moved | 64u | Total slab pages moved | 641| crawler_reclaimed | 64u | Total items freed by LRU Crawler | 642| crawler_items-checked | 64u | Total items examined by LRU Crawler | 643| lrutail_reflocked | 64u | Times LRU tail was found with active ref. | 644| | | Items can be evicted to avoid OOM errors. | 645| moves_to_cold | 64u | Items moved from HOT/WARM to COLD LRU's | 646| moves_to_warm | 64u | Items moved from COLD to WARM LRU | 647| moves_within_lru | 64u | Items reshuffled within HOT or WARM LRU's | 648| direct_reclaims | 64u | Times worker threads had to directly | 649| | | reclaim or evict items. | 650| lru_crawler_starts | 64u | Times an LRU crawler was started | 651| lru_maintainer_juggles | 652| | 64u | Number of times the LRU bg thread woke up | 653| slab_global_page_pool | 32u | Slab pages returned to global pool for | 654| | | reassignment to other slab classes. | 655| slab_reassign_rescues | 64u | Items rescued from eviction in page move | 656| slab_reassign_evictions_nomem | 657| | 64u | Valid items evicted during a page move | 658| | | (due to no free memory in slab) | 659| slab_reassign_chunk_rescues | 660| | 64u | Individual sections of an item rescued | 661| | | during a page move. | 662| slab_reassign_inline_reclaim | 663| | 64u | Internal stat counter for when the page | 664| | | mover clears memory from the chunk | 665| | | freelist when it wasn't expecting to. | 666| slab_reassign_busy_items | 667| | 64u | Items busy during page move, requiring a | 668| | | retry before page can be moved. | 669| log_worker_dropped | 64u | Logs a worker never wrote due to full buf | 670| log_worker_written | 64u | Logs written by a worker, to be picked up | 671| log_watcher_skipped | 64u | Logs not sent to slow watchers. | 672| log_watcher_sent | 64u | Logs written to watchers. | 673|-----------------------+---------+-------------------------------------------| 674 675Settings statistics 676------------------- 677CAVEAT: This section describes statistics which are subject to change in the 678future. 679 680The "stats" command with the argument of "settings" returns details of 681the settings of the running memcached. This is primarily made up of 682the results of processing commandline options. 683 684Note that these are not guaranteed to return in any specific order and 685this list may not be exhaustive. Otherwise, this returns like any 686other stats command. 687 688|-------------------+----------+----------------------------------------------| 689| Name | Type | Meaning | 690|-------------------+----------+----------------------------------------------| 691| maxbytes | size_t | Maximum number of bytes allows in this cache | 692| maxconns | 32 | Maximum number of clients allowed. | 693| tcpport | 32 | TCP listen port. | 694| udpport | 32 | UDP listen port. | 695| inter | string | Listen interface. | 696| verbosity | 32 | 0 = none, 1 = some, 2 = lots | 697| oldest | 32u | Age of the oldest honored object. | 698| evictions | on/off | When off, LRU evictions are disabled. | 699| domain_socket | string | Path to the domain socket (if any). | 700| umask | 32 (oct) | umask for the creation of the domain socket. | 701| growth_factor | float | Chunk size growth factor. | 702| chunk_size | 32 | Minimum space allocated for key+value+flags. | 703| num_threads | 32 | Number of threads (including dispatch). | 704| stat_key_prefix | char | Stats prefix separator character. | 705| detail_enabled | bool | If yes, stats detail is enabled. | 706| reqs_per_event | 32 | Max num IO ops processed within an event. | 707| cas_enabled | bool | When no, CAS is not enabled for this server. | 708| tcp_backlog | 32 | TCP listen backlog. | 709| auth_enabled_sasl | yes/no | SASL auth requested and enabled. | 710| item_size_max | size_t | maximum item size | 711| maxconns_fast | bool | If fast disconnects are enabled | 712| hashpower_init | 32 | Starting size multiplier for hash table | 713| slab_reassign | bool | Whether slab page reassignment is allowed | 714| slab_automove | bool | Whether slab page automover is enabled | 715| hash_algorithm | char | Hash table algorithm in use | 716| lru_crawler | bool | Whether the LRU crawler is enabled | 717| lru_crawler_sleep | 32 | Microseconds to sleep between LRU crawls | 718| lru_crawler_tocrawl | 719| | 32u | Max items to crawl per slab per run | 720| lru_maintainer_thread | 721| | bool | Split LRU mode and background threads | 722| hot_lru_pct | 32 | Pct of slab memory reserved for HOT LRU | 723| warm_lru_pct | 32 | Pct of slab memory reserved for WARM LRU | 724| expirezero_does_not_evict | 725| | bool | If yes, items with 0 exptime cannot evict | 726| idle_time | 0 | Drop connections that are idle this many | 727| | | seconds (0 disables) | 728| watcher_logbuf_size | 729| | 32u | Size of internal (not socket) write buffer | 730| | | per active watcher connected. | 731| worker_logbuf_size| 32u | Size of internal per-worker-thread buffer | 732| | | which the background thread reads from. | 733| track_sizes | bool | If yes, a "stats sizes" histogram is being | 734| | | dymamically tracked. | 735|-------------------+----------+----------------------------------------------| 736 737 738Item statistics 739--------------- 740CAVEAT: This section describes statistics which are subject to change in the 741future. 742 743The "stats" command with the argument of "items" returns information about 744item storage per slab class. The data is returned in the format: 745 746STAT items:<slabclass>:<stat> <value>\r\n 747 748The server terminates this list with the line 749 750END\r\n 751 752The slabclass aligns with class ids used by the "stats slabs" command. Where 753"stats slabs" describes size and memory usage, "stats items" shows higher 754level information. 755 756The following item values are defined as of writing. 757 758Name Meaning 759------------------------------ 760number Number of items presently stored in this class. Expired 761 items are not automatically excluded. 762number_hot Number of items presently stored in the HOT LRU. 763number_warm Number of items presently stored in the WARM LRU. 764number_cold Number of items presently stored in the COLD LRU. 765number_noexp Number of items presently stored in the NOEXP class. 766age Age of the oldest item in the LRU. 767evicted Number of times an item had to be evicted from the LRU 768 before it expired. 769evicted_nonzero Number of times an item which had an explicit expire 770 time set had to be evicted from the LRU before it 771 expired. 772evicted_time Seconds since the last access for the most recent item 773 evicted from this class. Use this to judge how 774 recently active your evicted data is. 775outofmemory Number of times the underlying slab class was unable to 776 store a new item. This means you are running with -M or 777 an eviction failed. 778tailrepairs Number of times we self-healed a slab with a refcount 779 leak. If this counter is increasing a lot, please 780 report your situation to the developers. 781reclaimed Number of times an entry was stored using memory from 782 an expired entry. 783expired_unfetched Number of expired items reclaimed from the LRU which 784 were never touched after being set. 785evicted_unfetched Number of valid items evicted from the LRU which were 786 never touched after being set. 787crawler_reclaimed Number of items freed by the LRU Crawler. 788lrutail_reflocked Number of items found to be refcount locked in the 789 LRU tail. 790moves_to_cold Number of items moved from HOT or WARM into COLD. 791moves_to_warm Number of items moved from COLD to WARM. 792moves_within_lru Number of times active items were bumped within 793 HOT or WARM. 794direct_reclaims Number of times worker threads had to directly pull LRU 795 tails to find memory for a new item. 796 797Note this will only display information about slabs which exist, so an empty 798cache will return an empty set. 799 800 801Item size statistics 802-------------------- 803CAVEAT: This section describes statistics which are subject to change in the 804future. 805 806The "stats" command with the argument of "sizes" returns information about the 807general size and count of all items stored in the cache. 808WARNING: In versions prior to 1.4.27 this command causes the cache server to 809lock while it iterates the items. 1.4.27 and greater are safe. 810 811The data is returned in the following format: 812 813STAT <size> <count>\r\n 814 815The server terminates this list with the line 816 817END\r\n 818 819'size' is an approximate size of the item, within 32 bytes. 820'count' is the amount of items that exist within that 32-byte range. 821 822This is essentially a display of all of your items if there was a slab class 823for every 32 bytes. You can use this to determine if adjusting the slab growth 824factor would save memory overhead. For example: generating more classes in the 825lower range could allow items to fit more snugly into their slab classes, if 826most of your items are less than 200 bytes in size. 827 828In 1.4.27 and after, this feature must be manually enabled. 829 830A "stats" command with the argument of "sizes_enable" will enable the 831histogram at runtime. This has a small overhead to every store or delete 832operation. If you don't want to incur this, leave it off. 833 834A "stats" command with the argument of "sizes_disable" will disable the 835histogram. 836 837It can also be enabled at starttime with "-o track_sizes" 838 839If disabled, "stats sizes" will return: 840 841STAT sizes_status disabled\r\n 842 843"stats sizes_enable" will return: 844 845STAT sizes_status enabled\r\n 846 847"stats sizes_disable" will return: 848 849STAT sizes_status disabled\r\n 850 851If an error happens, it will return: 852 853STAT sizes_status error\r\n 854STAT sizes_error [error_message]\r\n 855 856CAVEAT: If CAS support is disabled, you cannot enable/disable this feature at 857runtime. 858 859Slab statistics 860--------------- 861CAVEAT: This section describes statistics which are subject to change in the 862future. 863 864The "stats" command with the argument of "slabs" returns information about 865each of the slabs created by memcached during runtime. This includes per-slab 866information along with some totals. The data is returned in the format: 867 868STAT <slabclass>:<stat> <value>\r\n 869STAT <stat> <value>\r\n 870 871The server terminates this list with the line 872 873END\r\n 874 875|-----------------+----------------------------------------------------------| 876| Name | Meaning | 877|-----------------+----------------------------------------------------------| 878| chunk_size | The amount of space each chunk uses. One item will use | 879| | one chunk of the appropriate size. | 880| chunks_per_page | How many chunks exist within one page. A page by | 881| | default is less than or equal to one megabyte in size. | 882| | Slabs are allocated by page, then broken into chunks. | 883| total_pages | Total number of pages allocated to the slab class. | 884| total_chunks | Total number of chunks allocated to the slab class. | 885| get_hits | Total number of get requests serviced by this class. | 886| cmd_set | Total number of set requests storing data in this class. | 887| delete_hits | Total number of successful deletes from this class. | 888| incr_hits | Total number of incrs modifying this class. | 889| decr_hits | Total number of decrs modifying this class. | 890| cas_hits | Total number of CAS commands modifying this class. | 891| cas_badval | Total number of CAS commands that failed to modify a | 892| | value due to a bad CAS id. | 893| touch_hits | Total number of touches serviced by this class. | 894| used_chunks | How many chunks have been allocated to items. | 895| free_chunks | Chunks not yet allocated to items, or freed via delete. | 896| free_chunks_end | Number of free chunks at the end of the last allocated | 897| | page. | 898| mem_requested | Number of bytes requested to be stored in this slab[*]. | 899| active_slabs | Total number of slab classes allocated. | 900| total_malloced | Total amount of memory allocated to slab pages. | 901|-----------------+----------------------------------------------------------| 902 903* Items are stored in a slab that is the same size or larger than the 904 item. mem_requested shows the size of all items within a 905 slab. (total_chunks * chunk_size) - mem_requested shows memory 906 wasted in a slab class. If you see a lot of waste, consider tuning 907 the slab factor. 908 909 910Connection statistics 911--------------------- 912The "stats" command with the argument of "conns" returns information 913about currently active connections and about sockets that are listening 914for new connections. The data is returned in the format: 915 916STAT <file descriptor>:<stat> <value>\r\n 917 918The server terminates this list with the line 919 920END\r\n 921 922The following "stat" keywords may be present: 923 924|---------------------+------------------------------------------------------| 925| Name | Meaning | 926|---------------------+------------------------------------------------------| 927| addr | The address of the remote side. For listening | 928| | sockets this is the listen address. Note that some | 929| | socket types (such as UNIX-domain) don't have | 930| | meaningful remote addresses. | 931| state | The current state of the connection. See below. | 932| secs_since_last_cmd | The number of seconds since the most recently | 933| | issued command on the connection. This measures | 934| | the time since the start of the command, so if | 935| | "state" indicates a command is currently executing, | 936| | this will be the number of seconds the current | 937| | command has been running. | 938|---------------------+------------------------------------------------------| 939 940The value of the "state" stat may be one of the following: 941 942|----------------+-----------------------------------------------------------| 943| Name | Meaning | 944|----------------+-----------------------------------------------------------| 945| conn_closing | Shutting down the connection. | 946| conn_listening | Listening for new connections or a new UDP request. | 947| conn_mwrite | Writing a complex response, e.g., to a "get" command. | 948| conn_new_cmd | Connection is being prepared to accept a new command. | 949| conn_nread | Reading extended data, typically for a command such as | 950| | "set" or "put". | 951| conn_parse_cmd | The server has received a command and is in the middle | 952| | of parsing it or executing it. | 953| conn_read | Reading newly-arrived command data. | 954| conn_swallow | Discarding excess input, e.g., after an error has | 955| | occurred. | 956| conn_waiting | A partial command has been received and the server is | 957| | waiting for the rest of it to arrive (note the difference | 958| | between this and conn_nread). | 959| conn_write | Writing a simple response (anything that doesn't involve | 960| | sending back multiple lines of response data). | 961|----------------+-----------------------------------------------------------| 962 963 964 965Other commands 966-------------- 967 968"flush_all" is a command with an optional numeric argument. It always 969succeeds, and the server sends "OK\r\n" in response (unless "noreply" 970is given as the last parameter). Its effect is to invalidate all 971existing items immediately (by default) or after the expiration 972specified. After invalidation none of the items will be returned in 973response to a retrieval command (unless it's stored again under the 974same key *after* flush_all has invalidated the items). flush_all 975doesn't actually free all the memory taken up by existing items; that 976will happen gradually as new items are stored. The most precise 977definition of what flush_all does is the following: it causes all 978items whose update time is earlier than the time at which flush_all 979was set to be executed to be ignored for retrieval purposes. 980 981The intent of flush_all with a delay, was that in a setting where you 982have a pool of memcached servers, and you need to flush all content, 983you have the option of not resetting all memcached servers at the 984same time (which could e.g. cause a spike in database load with all 985clients suddenly needing to recreate content that would otherwise 986have been found in the memcached daemon). 987 988The delay option allows you to have them reset in e.g. 10 second 989intervals (by passing 0 to the first, 10 to the second, 20 to the 990third, etc. etc.). 991 992"cache_memlimit" is a command with a numeric argument. This allows runtime 993adjustments of the cache memory limit. It returns "OK\r\n" or an error (unless 994"noreply" is given as the last parameter). If the new memory limit is higher 995than the old one, the server may start requesting more memory from the OS. If 996the limit is lower, and slabs_reassign+automove are enabled, free memory may 997be released back to the OS asynchronously. 998 999"version" is a command with no arguments: 1000 1001version\r\n 1002 1003In response, the server sends 1004 1005"VERSION <version>\r\n", where <version> is the version string for the 1006server. 1007 1008"verbosity" is a command with a numeric argument. It always succeeds, 1009and the server sends "OK\r\n" in response (unless "noreply" is given 1010as the last parameter). Its effect is to set the verbosity level of 1011the logging output. 1012 1013"quit" is a command with no arguments: 1014 1015quit\r\n 1016 1017Upon receiving this command, the server closes the 1018connection. However, the client may also simply close the connection 1019when it no longer needs it, without issuing this command. 1020 1021 1022UDP protocol 1023------------ 1024 1025For very large installations where the number of clients is high enough 1026that the number of TCP connections causes scaling difficulties, there is 1027also a UDP-based interface. The UDP interface does not provide guaranteed 1028delivery, so should only be used for operations that aren't required to 1029succeed; typically it is used for "get" requests where a missing or 1030incomplete response can simply be treated as a cache miss. 1031 1032Each UDP datagram contains a simple frame header, followed by data in the 1033same format as the TCP protocol described above. In the current 1034implementation, requests must be contained in a single UDP datagram, but 1035responses may span several datagrams. (The only common requests that would 1036span multiple datagrams are huge multi-key "get" requests and "set" 1037requests, both of which are more suitable to TCP transport for reliability 1038reasons anyway.) 1039 1040The frame header is 8 bytes long, as follows (all values are 16-bit integers 1041in network byte order, high byte first): 1042 10430-1 Request ID 10442-3 Sequence number 10454-5 Total number of datagrams in this message 10466-7 Reserved for future use; must be 0 1047 1048The request ID is supplied by the client. Typically it will be a 1049monotonically increasing value starting from a random seed, but the client 1050is free to use whatever request IDs it likes. The server's response will 1051contain the same ID as the incoming request. The client uses the request ID 1052to differentiate between responses to outstanding requests if there are 1053several pending from the same server; any datagrams with an unknown request 1054ID are probably delayed responses to an earlier request and should be 1055discarded. 1056 1057The sequence number ranges from 0 to n-1, where n is the total number of 1058datagrams in the message. The client should concatenate the payloads of the 1059datagrams for a given response in sequence number order; the resulting byte 1060stream will contain a complete response in the same format as the TCP 1061protocol (including terminating \r\n sequences). 1062