Introduction

There are many web and GUI interfaces available for accessing Memcached server instances, my personal favourite is phpMemCacheAdmin. Sometimes however you may need to access a Memcached instance from the command line.

In this tutorial, I will show you how to connect to a Memcached instances using Telnet, how to get statistics on the server, and how to read and delete data from the cache.

Making a connection

To make a connection to Memcached using Telnet, use the following command:

[jcollins@redhat memcached]$ telnet localhost 11211
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.

If at any time you wish to terminate the Telnet session, simply type "quit" and hit return:

quit
Connection closed by foreign host.
[jcollins@redhat memcached]$

Accessing statistics

You can get an overview of the important statistics of your Memcached server by running the stats command once connected:

stats
STAT pid 22622
STAT uptime 69300
STAT time 1296733424
STAT version 1.2.5
STAT pointer_size 32
STAT rusage_user 0.117982
STAT rusage_system 0.145977
STAT curr_items 3
STAT total_items 10
STAT bytes 1174
STAT curr_connections 2
STAT total_connections 13
STAT connection_structures 3
STAT cmd_get 10
STAT cmd_set 10
STAT get_hits 9
STAT get_misses 1
STAT evictions 0
STAT bytes_read 4593
STAT bytes_written 7388
STAT limit_maxbytes 268435456
STAT threads 1
END

Some useful information is returned, such as the uptime for the server, the version of Memcached installed, the total number of items in the cache, and the amount of client connections to the instance.

Accessing slabs

According to the Memcached FAQ:

Memory is allocated in chunks internally and constantly reused. Since memory is broken into different size slabs, you do waste memory if your items do not fit perfectly into the slab the server chooses to put it in.

So Memcached allocates your data into different "slabs" (think of these as partitions) of memory automatically, based on the size of your data, which in turn makes memory allocation more optimal.

To list the slabs in the instance you are connected to, use the stats slab command:

stats slabs
STAT 1:chunk_size 88
STAT 1:chunks_per_page 11915
STAT 1:total_pages 1
STAT 1:total_chunks 11915
STAT 1:used_chunks 11915
STAT 1:free_chunks 0
STAT 1:free_chunks_end 11914
STAT 6:chunk_size 296
STAT 6:chunks_per_page 3542
STAT 6:total_pages 1
STAT 6:total_chunks 3542
STAT 6:used_chunks 3541
STAT 6:free_chunks 1
STAT 6:free_chunks_end 3541
STAT 7:chunk_size 376
STAT 7:chunks_per_page 2788
STAT 7:total_pages 1
STAT 7:total_chunks 2788
STAT 7:used_chunks 2788
STAT 7:free_chunks 0
STAT 7:free_chunks_end 2787
STAT 8:chunk_size 472
STAT 8:chunks_per_page 2221
STAT 8:total_pages 1
STAT 8:total_chunks 2221
STAT 8:used_chunks 2220
STAT 8:free_chunks 1
STAT 8:free_chunks_end 2218
STAT active_slabs 4
STAT total_malloced 4193552
END

A more useful command is the stats items, which will give you a list of slabs which includes a count of the items store within each slab:

stats items
STAT items:1:number 1
STAT items:1:age 35
STAT items:1:evicted 0
STAT items:1:outofmemory 0
STAT items:7:number 1
STAT items:7:age 69596
STAT items:7:evicted 0
STAT items:7:outofmemory 0
STAT items:8:number 2
STAT items:8:age 69627
STAT items:8:evicted 0
STAT items:8:outofmemory 0
END

Accessing and deleting data

Now that you know how to list slabs, you can browse inside each slab to list the items contained within by using the stats cachedump command, which has the following signature:

stats cachedump [slab ID] [number of items, 0 for all items]

For example...

stats cachedump 1 0
ITEM testkey [9 b; 1296857316 s]
END

..tells us that there is one item in the slab 1 with the key testkey. If we want to get the actual value of that item, we can use the get [key] command:

get testkey
VALUE testkey 0 9
test data
END

Finally, if you want to delete an item from the cache you can use the delete [key] command:

END
delete testkey
DELETED

Conclusion

Memcached is an amazing piece of software in terms of its many potential applications to increase web application performance. While powerful, it is simple to use and configure, and I find the API very intuitive. I am looking forward to using it on a many projects in the future.

---

Updated 2020 : note that the above post may be out-of-date, given this post was originally published in 2011, but is left here for archival purposes. There may be better methods available now.