С чего начать
Подключение и базовые команды
Memcached использует простой текстовый протокол на порту 11211. Команда set принимает flags (32-битное целое, непрозрачное для сервера), exptime (время жизни в секундах, 0 — без истечения) и размер в байтах. Значения хранятся как сырые байты — сервер их никогда не разбирает и не изменяет. Утилита memcached-tool входит в комплект сервера и удобна для быстрого просмотра статистики.
# connect to a memcached server
telnet localhost 11211
# or use the memcached-tool (ships with the server)
memcached-tool localhost:11211 stats
# set a key (flags, exptime, bytes)
set mykey 0 3600 5
hello
# get a key
get mykey
# delete a key
delete mykeyОбзор протокола
Memcached поддерживает и ASCII-текстовый протокол (удобен для telnet/netcat), и бинарный (эффективнее, поддерживает аутентификацию SASL и атомарные операции). В бинарном протоколе используется фиксированный заголовок на 24 байта, и большинство продакшен-клиентов предпочитают его. Оба протокола работают с одним и тем же хранилищем ключ-значение.
# Two protocols available:
# 1) ASCII text protocol (human-readable, telnet-friendly)
# 2) Binary protocol (lower overhead, SASL auth, request pipelining)
# text protocol example
set foo 0 0 3
bar
# -> STORED
# binary protocol needs a client (e.g. python binary protocol):
# 0x80 (request) | opcode | keylen | extras | datatype | reserved
# bodylen | opaque | cas | extras | key | value
# both share the same in-memory data store
# check server version (text)
version
# -> VERSION 1.6.24Правила и ограничения ключей
Длина ключа ограничена 250 байтами; в текстовом протоколе в ключе нельзя использовать пробелы и управляющие символы. Максимальный размер значения по умолчанию — 1 МБ (увеличивается флагом -I, например -I 4m). Ключи не копируются: Memcached хранит их внутри элемента, поэтому длинные ключи занимают больше памяти. Используйте короткие структурированные ключи вроде user:1001 вместо длинных описательных имён.
# Keys: max 250 bytes, no spaces or newlines (text protocol)
# Controls: max 1MB default value (configurable via -I)
# valid keys
set user:1001 0 0 5
alice
set product:sku-42 0 0 3
xyz
# INVALID keys (text protocol)
# set "with spaces" ... -> spaces not allowed
# set mykey\n ... -> newlines not allowed
# large value exceeds 1MB default
set bigkey 0 0 1048577
# -> SERVER_ERROR object too large for cache
# increase max item size at startup (-I in MB)
# memcached -m 256 -I 4mТипичные сценарии использования
Memcached лучше всего подходит для кеширования временных производных данных: результатов запросов к базе, сессий, отрендеренных фрагментов страниц, счётчиков rate limiting и дорогих вычислений. Он намеренно прост: нет персистентности, репликации и сложных типов данных. Относитесь к нему как к энергозависимому LRU-кешу — никогда не храните там данные, которые нельзя восстановить из системы-источника.
# 1) Database query cache
set user:1001:profile 0 600 48
{"id":1001,"name":"Alice","email":"[email protected]"}
# 2) Session storage (with TTL)
set sess:abc123 0 1800 64
{"userId":1001,"loginAt":1700000000,"role":"admin"}
# 3) Rendered HTML fragment cache
set page:home:en 0 300 128
<html><body>Hello</body></html>
# 4) Rate-limit counters
incr ratelimit:ip:1.2.3.4 1
# 5) Computed result cache (expensive aggregation)
set report:daily:20240101 0 3600 256
{"visits":1234,"signups":56}Обзор архитектуры
Memcached — это распределённый кеш из независимых серверов без координации. В самом сервере нет кластеризации, репликации и отказоустойчивости: вся логика распределения живёт в клиенте (согласованное хеширование). Каждый узел владеет своей непересекающейся частью пространства ключей; если узел падает, его данные теряются, а клиенты перенаправляют запросы. Благодаря этому сервер остаётся очень простым и быстрым — ценой долговечности.
# Memcached is a pool of independent servers (no clustering built-in)
#
# +---------+ +---------+ +---------+
# | mc:11211| | mc:11211| | mc:11211|
# +---------+ +---------+ +---------+
# ^ ^ ^
# | | |
# +----+------------+-------------+----+
# | CLIENT (consistent hashing) |
# +------------------------------------+
#
# - Each server owns a disjoint slice of the keyspace
# - Sharding is done by the CLIENT (consistent hashing)
# - Servers do NOT talk to each other (no replication, no failover)
# - A server down = its keys are lost; clients reroute to the ring
# horizontal scale = add more servers to the ring
# vertical scale = bigger -m memory per serverБазовые команды (set / get / delete)
set — сохранить значение
set безусловно сохраняет значение, перезаписывая существующий ключ. flags — 32-битное целое, которое сервер хранит, но никогда не интерпретирует: клиенты используют его для кодирования формата сериализации (например, 1 = JSON, 2 = сжато). exptime 0 означает отсутствие истечения; Unix-время больше 30 дней трактуется как абсолютный момент. noreply пропускает ответ для записи «выстрелил и забыл» (быстрее, но без сообщения об ошибках).
# syntax: set <key> <flags> <exptime> <bytes> [noreply]\r\n<data>\r\n
# response: STORED | NOT_STORED
set greeting 0 0 5
hello
# -> STORED
# with flags (app-defined 32-bit int, e.g. mark as JSON=1)
set config 1 0 14
{"a":1,"b":2}
# -> STORED
# with expiration (3600 seconds) and noreply
set token 0 3600 8 noreply
s3cr3t00
# -> (no response)
# overwrite an existing key
set greeting 0 0 7
goodbye
# -> STOREDget — получить значения
get извлекает один или несколько ключей за один сетевой обход — пакетные запросы (multi-get) критичны для производительности. Каждая возвращённая строка VALUE повторяет flags, чтобы клиент знал, как десериализовать данные. Отсутствующие ключи молча пропускаются (без ошибки). Ответ завершается строкой END. Большие multi-get стоит разбивать на части, чтобы не блокировать один поток сервера.
# single key
get greeting
# VALUE greeting 0 7
# goodbye
# END
# multiple keys in one request (batched)
get user:1 user:2 user:3
# VALUE user:1 0 5
# alice
# VALUE user:3 0 3
# bob
# END (user:2 missing -> simply omitted)
# response format: VALUE <key> <flags> <bytes>\r\n<data>\r\n ... END
# flags lets the client decode (e.g. decompress / parse JSON)
# non-existent key
get nope
# END (no VALUE line at all)gets — получить с CAS-токеном
gets (get-extended) работает как get, но добавляет к каждой строке VALUE токен cas_unique. Это 64-битное целое меняется при каждой записи и лежит в основе оптимистичной блокировки Memcached (CAS). Используйте gets + cas вместе, чтобы избежать потерянных обновлений, когда несколько клиентов меняют один ключ. Токен непрозрачен — не полагайтесь на его значение и монотонность между ключами.
# gets returns a CAS unique identifier for optimistic concurrency
gets greeting
# VALUE greeting 0 7 12
# goodbye
# END
# ^ cas_unique = 12
# the cas_unique changes every time the key is written
set greeting 0 0 5
hello
gets greeting
# VALUE greeting 0 5 13
# hello
# END (cas_unique is now 13)
# use cas_unique with the cas command for safe updates
cas greeting 0 0 5 13
world
# -> STOREDdelete — удалить ключ
delete удаляет один ключ и возвращает DELETED или NOT_FOUND. Удаления по шаблону или маске нет: в Memcached вообще отсутствует команда перечисления ключей, поэтому массовое удаление должен отслеживать сам прикладной код (хранит е набор ключей в другом месте или используйте схемы с версионированием пространств имён). Добавьте noreply, чтобы не ждать ответа. Освобождённая память возвращается в свой slab и переиспользуется.
# delete a single key
delete greeting
# -> DELETED
# delete a non-existent key
delete nope
# -> NOT_FOUND
# with noreply (fire-and-forget)
delete stalekey 0 noreply
# -> (no response)
# delete does NOT support patterns or wildcards
# delete user:* <- INVALID, only deletes a key literally named "user:*"
# to bulk-delete, list keys yourself then delete each
# (memcached has no KEYS/SCAN command — track keys in your app)touch и gat — обновление срока жизни
touch (1.4.8+) обновляет срок жизни ключа, не передавая значение, — дешевле, чем get+set для продления сессии. gat извлекает значение и атомарно обновляет TTL за один обход — идеально для чтения сессий, срок которых нужно продлить. gats дополнительно возвращает CAS-токен. Используйте их вместо get+set, чтобы избежать гонки, когда значение меняется между операциями.
# touch: change a key's expiration without fetching the value
touch session 3600
# -> TOUCHED
touch session 0 # make it never expire
# -> TOUCHED
# gat: get-and-touch — fetch value AND update expiration in one op
gat 3600 session
# VALUE session 0 64
# {...}
# END
# gats: get-and-touch with CAS token
gats 3600 session
# VALUE session 0 64 42
# {...}
# END
# touch a missing key
touch nope 60
# -> NOT_FOUNDКоманды записи (add / replace / append / prepend)
add — сохранить, только если ключа нет
add сохраняет значение, только если ключ ещё НЕ существует, иначе возвращает NOT_STORED. Это канонический способ ленивой инициализации ключей (счётчиков, блокировок) без гонки. Вместе с incr/decr он образует безопасный шаблон счётчика: add создаёт значение 0, затем incr. В отличие от Redis SETNX, у add нет сокращения для TTL — указывайте exptime в команде.
# add fails if the key already exists
add newkey 0 0 5
hello
# -> STORED
add newkey 0 0 5
world
# -> NOT_STORED (key already exists)
# common pattern: initialize a counter only once
add counter:daily 0 0 1
0
# -> STORED on first run, NOT_STORED after
# then use incr to bump it
incr counter:daily 1
# -> 1replace — сохранить, только если ключ есть
replace сохраняет значение, только если ключ УЖЕ существует, — зеркало add. Он мешает случайно создать запись кеша из устаревшего пути обновления. Возвращает NOT_STORED, если ключа нет. Используйте его, когда запись должна обновить существующий кеш, но не создавать новую запись (например, фоновое обновление не должно воскрешать вытесненный ключ).
# replace fails if the key does NOT exist
replace missing 0 0 5
hello
# -> NOT_STORED (key doesn't exist)
set existing 0 0 3
foo
# -> STORED
replace existing 0 0 3
bar
# -> STORED (key existed, value updated)
# useful for updating cached data only if it was already cached
# (don't accidentally create a cache entry from a stale write)
replace cached:user:1 0 600 64
{"name":"Alice"}append — дописать к существующему значению
append добавляет данные в конец существующего значения и возвращает NOT_STORED, если ключа нет. Аргументы flags и exptime принимаются, но игнорируются — значение сохраняет исходные метаданные. Это удобно для наращивания строк лога или буферов на месте без чтения-изменения-записи. Осторожно: итоговое значение всё равно должно укладываться в лимит 1 МБ.
# append adds data to the END of an existing value
set logline 0 0 5
hello
# -> STORED
append logline 0 0 6
world
# -> STORED
get logline
# VALUE logline 0 11
# hello world
# END
# append to a non-existent key
append nolog 0 0 3
abc
# -> NOT_STORED (key must exist)
# flags and exptime are IGNORED on append/prepend (value keeps old metadata)prepend — вставить перед существующим значением
prepend — зеркало append: добавляет данные в НАЧАЛО существующего значения. Как и append, требует наличия ключа и игнорирует flags/exptime. Полезен для добавления заголовков и префиксов к буферизованному значению. append и prepend НЕ являются атомарными «чтение-изменение-запись» в том смысле, что не возвращают результат, но на сервере это атомарные операции.
# prepend adds data to the START of an existing value
set greeting 0 0 5
world
# -> STORED
prepend greeting 0 0 6
hello
# -> STORED
get greeting
# VALUE greeting 0 11
# hello world
# END
# prepend to non-existent key
prepend nope 0 0 3
abc
# -> NOT_STORED
# flags/exptime ignored — only the value bytes changeСравнение команд записи
Шесть команд записи Memcached (set, add, replace, append, prepend, cas) различаются только предусловием записи. set безусловен; add/replace зависят от существования ключа; append/prepend изменяют значение на месте и игнорируют метаданные; cas проверяет CAS-токен из gets. Правильный выбор команды превращает гонку «чтение-изменение-запись» в одну атомарную операцию сервера.
# When does each command succeed?
#
# set -> ALWAYS (create or overwrite)
# add -> only if key does NOT exist
# replace -> only if key ALREADY exists
# append -> only if key exists (adds to end, ignores flags/exptime)
# prepend -> only if key exists (adds to start, ignores flags/exptime)
#
# All return STORED / NOT_STORED / EXISTS / NOT_FOUND as appropriate.
# set: overwrite unconditionally
# add: lazy init (counters, locks)
# replace: refresh only if already cached
# append: grow a buffer / log
# prepend: stack headers
# all accept [noreply] to skip the responseCAS (сравнение и замена)
gets — получить CAS-токен
gets (get-extended) — читающая половина CAS. Он возвращает значение и 64-битный токен cas_unique, который, по гарантии сервера, меняется при любом изменении ключа. Вы сохраняете токен и передаёте его в cas; если токен всё ещё совпадает, запись проходит. Без gets безопасный CAS невозможен: обычный get токен не возвращает.
# gets is get + a 64-bit cas_unique token
gets counter
# VALUE counter 0 1 7
# 5
# END
# ^ cas_unique = 7
# the token is opaque and changes on EVERY write to the key
set counter 0 0 1
5
gets counter
# VALUE counter 0 1 8 <- token changed to 8
# fetch multiple keys with tokens in one call
gets a b c
# VALUE a 0 3 11
# ...
# VALUE c 0 3 19
# ...cas — условная запись
cas записывает значение, только если токен cas_unique всё ещё совпадает с тем, что вернул gets. STORED означает, что запись применена; EXISTS — что другой клиент изменил ключ первым (токен не совпал); NOT_FOUND — что ключ удалён. Это оптимистичная блокировка: при EXISTS повторяйте весь цикл gets→изменение→cas. Так вы избегаете потерянных обновлений без блокиров ок на сервере.
# syntax: cas <key> <flags> <exptime> <bytes> <cas_unique> [noreply]
gets counter
# VALUE counter 0 1 8 <- token is 8
# 5
cas counter 0 0 1 8
6
# -> STORED (token matched, write applied)
# a concurrent write changed the token in the meantime
cas counter 0 0 1 8 # stale token 8, but key is now on token 9
6
# -> EXISTS (token mismatch, someone else wrote first)Сценарий CAS: безопасный счётчик
CAS решает проблему потерянных обновлений, когда нужна семантика «чтение-изменение-запись» (например, обновление JSON-объекта внутри записи кеша). При EXISTS нужно заново прочитать через gets, повторить преобразование и снова вызвать cas — обычно с ограничением числа попыток, чтобы избежать livelock. Для чисто целочисленных счётчиков incr/decr проще и атомарны; CAS нужен только для структурированных значений.
# read-modify-write with get+set is RACY:
# get counter -> 5 (client A)
# get counter -> 5 (client B)
# set counter 6 (A writes 6)
# set counter 6 (B writes 6, LOST A's increment!)
# safe pattern with gets/cas:
gets counter # token = 8, value = 5
newval = 5 + 1
cas counter 0 0 1 8 # 8 -> STORED, value = 6
# on EXISTS, retry the whole loop:
gets counter # token = 9, value = 6
cas counter 0 0 1 9 # -> STORED, value = 7
# for plain counters prefer incr/decr (atomic, no CAS needed)Сбой CAS и повторы
Надёжный цикл CAS обрабатывает три исхода: ключа нет (используйте add, а при NOT_STORED повторяйте), токен совпал (STORED, готово) и токен не совпал (EXISTS, повтор). Ограничивайте число повторов, чтобы не зациклиться при высокой конкуренции. Если ключ действительно отсутствует, предпочитайте add вместо set, чтобы два клиента, создающие его одновременно, не затёрли друг друга.
# pseudocode for a CAS retry loop
max_retries = 5
for i in range(max_retries):
res = client.gets(key) # value + cas token
if res is None:
# key missing -> use add to create it race-free
if client.add(key, new_value, ttl):
break
else:
continue # someone else created it; retry
old_val, cas_token = res
new_val = transform(old_val) # your read-modify logic
if client.cas(key, new_value, ttl, cas_token):
break # STORED
# else EXISTS -> loop and retry
else:
raise Exception("CAS failed after retries")Ограничения CAS
CAS работает только с одним ключом: в Memcached нет многоключевых транзакций вроде Redis MULTI/EXEC. Он оптимистичен, а не пессимистичен: при сильной конкуренции многие записи получат EXISTS и уйдут на повтор, поэтому шардируйте горячие ключи. cas_unique привязан к ключу и непрозрачен — не сравнивайте его между ключами и не предполагайте порядок. Если ключ вытеснен и создан заново, токен сбрасывается, поэтому NOT_FOUND стоит считать началом с нуля, а не сбоем.
# 1) CAS only protects a SINGLE key — no multi-key transactions
# (memcached has no MULTI/EXEC like Redis)
#
# 2) CAS tokens are per-key and opaque — never compare across keys
#
# 3) CAS does NOT lock the key; it's optimistic — high contention
# means many retries (consider sharding the hot key)
#
# 4) The binary protocol exposes cas more cleanly; some ASCII quirks
# exist in older servers
#
# 5) cas_unique may RESET if a key is evicted and re-created —
# treat absence (NOT_FOUND) as a fresh start, not a token failure
# for multi-key atomicity, use app-level locks (e.g. add-based lock)Счётчики (incr / decr)
incr — атома рное увеличение
incr атомарно прибавляет положительное целое к ключу, значение которого — десятичная строка, и возвращает новое значение. Операция полностью атомарна для параллельных клиентов — потерянных обновлений нет. Значение должно быть 64-битным беззнаковым числом в ASCII (без знаков и дробной части). incr для отсутствующего ключа возвращает NOT_FOUND, для нечисловых данных — ошибку. Автосоздания нет — сначала используйте add.
# syntax: incr <key> <value> [noreply]
# the key's value MUST be a numeric string (ASCII digits)
set views 0 0 1
5
# -> STORED
incr views 1
# -> 6
incr views 10
# -> 16
# returns the NEW value as a decimal string
# incrementing a non-numeric value
set name 0 0 5
alice
incr name 1
# -> CLIENT_ERROR cannot increment or decrement non-numeric value
# incr on a missing key
incr missing 1
# -> NOT_FOUNDdecr — атомарное уменьшение
decr атомарно вычитает из числового значения и возвращает результат. Он ограничен снизу нулём и никогда не даёт отрицательного числа — это удобно для счётчиков запасов, но не позволяет отслеживать отрицательные балансы. Как и incr, требует ASCII-цифр и существующего ключа (иначе NOT_FOUND).
# syntax: decr <key> <value> [noreply]
set views 0 0 2
16
# -> STORED
decr views 1
# -> 15
decr views 10
# -> 5
# decr NEVER goes negative — stops at 0
decr views 100
# -> 0
# decr a missing key
decr missing 1
# -> NOT_FOUND
# decr a non-numeric value -> CLIENT_ERRORИнициализация счётчиков
Поскольку incr/decr возвращают NOT_FOUND для отсутствующего ключа, счётчики нужно инициализировать через add (без гонки: первый вызов создаёт 0, остальные получают NOT_STORED и сразу переходят к incr). Никогда не инициализируйте через set счётчик, который потом инкрементируете: set перезаписывает безусловно и гоняется с параллельными инкрементами. Пространство имён по дате плюс TTL позволяют счётчикам истекать автоматически.
# incr/decr do NOT create keys — initialize with add first
# race-free counter init: add creates at "0" only if absent
add counter:daily 0 86400 1
0
# -> STORED (first caller wins) or NOT_STORED (already exists)
# now safe to increment from any client
incr counter:daily 1
# -> 1
# alternative: set then incr (but set+incr is racy for resets)
# For a daily counter, key by date so it auto-expires:
# counter:2024-01-01
# counter:2024-01-02Сценарии использования счётчиков
Счётчики отлично подходят для rate limiting (ключ по IP+минуте с TTL 60 с), статистики просмотров и скачиваний, подсчёта дневной активности, учёта запасов и метрик раскатки. Они атомарны и дешевы, поэтому выдерживают очень высокий темп записи. Для rate limiting выбирайте гранулярность ключа (по пользователю, по IP) и TTL под ваше окно; помните, что decr ограничен нулём, так что запасы не уйдут в минус.
# rate limiting (per IP per minute)
add ratelimit:1.2.3.4:2024010112 0 60 1
0
incr ratelimit:1.2.3.4:2024010112 1
# if result > 100 -> reject request
# view/download counters
incr article:42:views 1
# daily active users (with a SET of user ids tracked elsewhere)
incr dau:20240101 1
# inventory / stock (decrement on purchase)
decr product:42:stock 1
# if result == 0 -> out of stock
# feature-flag rollout counters
incr flag:newui:shown 1Ограничения счётчиков
Счётчики — только беззнаковые 64-битные целые: ни чисел с плавающей точкой, ни отрицательных зн ачений, ни знаков. incr/decr никогда не создают ключ автоматически. decr ограничен нулём. Поскольку значение — просто строка, случайный set/replace перезапишет его и затрёт параллельные инкременты; инициализируйте через add и далее используйте только incr/decr. Для чисел с плавающей точкой или многополевых счётчиков применяйте CAS со структурированным значением.
# 1) values must be unsigned 64-bit integers (no decimals, no signs)
# incr/decr on "3.14" or "-5" -> CLIENT_ERROR
#
# 2) no auto-create — must add/set first; incr on missing = NOT_FOUND
#
# 3) decr floors at 0 — cannot represent negative balances
#
# 4) the counter is just a string; set/add/replace/cas OVERWRITE it,
# which can clobber concurrent incr/decr (use add only to init)
#
# 5) for float counters or complex updates, use CAS on a JSON blob
# to RESET a counter, use set (not decr-to-zero) — but watch for racesСрок жизни и TTL
set с истечением срока
exptime задаётся в секундах: 0 — никогда не истекает, значения до 2592000 (30 дней) — относительный TTL, а большие значения трактуются как абсолютное Unix-время. Просроченные элементы не удаляются ровно в ту же секунду: Memcached использует ленивое истечение (проверка при обращении) плюс фоновый LRU-обходчик, поэтому устаревший ключ может лежать, пока к нему не обратятся или пока его не вытеснят.
# exptime is the 4th arg to all storage commands (seconds)
# 0 = no expiration (live until evicted)
set session 0 0 5 # never expire
alice
set session 0 1800 5 # expire in 1800 seconds (30 min)
alice
# exptime > 30 days (2592000 s) is treated as a UNIX timestamp
set archive 0 1735689600 5 # expires at 2025-01-01 00:00 UTC
alice
# common TTLs
# 60 -> 1 minute (rate limit windows)
# 3600 -> 1 hour (short cache)
# 86400 -> 1 day (daily cache)
# 0 -> forever (until LRU evicts)touch — обновить TTL
touch (1.4.8+) обновляет TTL ключа на месте, не передавая значение, — гораздо дешевле get+set для скользящих сессий. Установите exptime=1 для мягкого удаления (элемент сразу становится просроченным). Действует то же правило 30 дней: меньше — относительный TTL, больше — абсолютное время. touch возвращает NOT_FOUND для отсутствующих ключей, и вызывающий код должен трактовать это как «не закешировано».
# touch: change a key's TTL without fetching the value
# syntax: touch <key> <exptime> [noreply]
set session 0 3600 5
alice
# extend the session by another hour
touch session 3600
# -> TOUCHED
# make it never expire
touch session 0
# -> TOUCHED
# expire it immediately (poor man's delete via TTL)
touch session 1
# -> TOUCHED (effectively deleted on next access)
touch missing 60
# -> NOT_FOUNDgat и gats — получить и продлить
gat (1.6+) атомарно объединяет get и touch за один обход — идеально для чтения сессий с продлением срока. gats дополнительно возвращает CAS-токен. Отдельные get+touch создают окно, в котором TTL не продлевается, и удваивают число обходов; gat решает обе проблемы. Для скользящего чтения нескольких ключей gat принимает несколько ключей.
# gat: fetch value AND update TTL in one round-trip
# syntax: gat <exptime> <key>
gat 3600 session
# VALUE session 0 5
# alice
# END
# gats: get-and-touch with CAS token
gats 3600 session
# VALUE session 0 5 42
# alice
# END
# ideal for session reads that should refresh the TTL:
# - one network round-trip instead of get + touch
# - atomic: no window where TTL isn't refreshed
# multiple keys: gat <exptime> <key1> <key2> ...
gat 3600 a b cПоведение истечения
Истечение в Memcached по умолчанию ленивое: ключ удаляется только при обращении, поэтому устаревшие данные могут занимать память до вытеснения. LRU-обходчик (1.4.24+) добавляет фоновое сканирование, которое проактивно освобождает просроченные элементы в каждом slab, предотвращая потери памяти. Включайте его в продакшене: lru_crawler enable. Но всё равно никогда не полагайтесь на точность момента истечения для корректности логики.
# Memcached does NOT actively scan for expired keys every second.
# Expiration is LAZY: a key is checked when accessed (get/gets/touch).
#
# A background "LRU crawler" (1.4.24+) periodically sweeps slabs to
# free expired items so memory is reclaimed even if never accessed.
#
# stats lru_crawler # is the crawler enabled?
# lru_crawler enable # turn it on
# lru_crawler sleep 100 # microseconds between slab visits
# lru_crawler tocrawl 1000 # max items to inspect per slab per pass
# an expired-but-not-yet-reaped key:
get expiredkey
# -> END (treated as missing, memory freed for its slab)Практика работы с TTL
Всегда задавайте TTL: записи без срока ведут к неограниченному росту памяти и багам из-за устаревших данных. Добавляйте случайный разброс (±5–10%) к TTL, чтобы синхронные истечения не устраивали лавину на источник. Неймспейсите изменчивые данные по дате, чтобы старые записи истекали сами. При промахе пересчитывайте и сохраняйте в том же коде, чтобы кеш оставался тёплым. Для явной инвалидации используйте delete, а не TTL=1.
# 1) ALWAYS set a TTL on cache entries — never store forever (0)
# unless you have an explicit invalidation path.
#
# 2) add jitter to avoid thundering herds:
ttl = base_ttl + random(0, 300) # +/- 5 minutes
#
# 3) namespace by time so old keys auto-expire:
set report:2024-01-01 0 86400 N # yesterday's report, 1-day TTL
#
# 4) use longer TTLs for stable data, shorter for volatile data
#
# 5) on a cache miss, recompute AND set with TTL in ONE path
#
# 6) don't use exptime=1 as a "delete" in production — use deleteКоманды статистики
stats — общий обзор
stats выдаёт основные метрики сервера: cmd_get/cmd_set (всего операций), get_hits/get_misses (доля попаданий = hits/cmd_get), evictions (элементы, вытесненные из-за нехватки памяти), curr_items, bytes против limit_maxbytes и число соединений. Доля попаданий и вытеснения — первые два показателя, на которые стоит смотреть. Это основа любого мониторинга Memcached.
# general server statistics
stats
# STAT pid 1234
# STAT uptime 3600
# STAT curr_connections 10
# STAT total_connections 1024
# STAT cmd_get 50000
# STAT cmd_set 12000
# STAT get_hits 45000
# STAT get_misses 5000
# STAT evictions 12
# STAT bytes 8388608
# STAT limit_maxbytes 67108864
# STAT curr_items 4321
# ...
# END
# hit rate = get_hits / cmd_get (here 90%)
# watch evictions — rising = memory pressurestats items — счётчики по slab-классам
stats items показывает для каждого slab-класса, сколько элементов он хранит (number) и возраст самого давнего по последней записи элемента (age). Класс с большим number и малым age постоянно крутится; класс с большим age хранит долгоживущие данные. Это первое место, куда смотреть при настройке размера чанков или выяснении, почему вытесняется конкретный диапазон размеров.
# item counts and age per slab class
stats items
# STAT items:1:number 100
# STAT items:1:age 1200
# STAT items:2:number 250
# STAT items:2:age 3600
# STAT items:5:number 3
# STAT items:5:age 60
# ...
# END
# items:<slabid>:number -> how many items live in that slab class
# items:<slabid>:age -> age of the LRU item (seconds since stored)
# use this to see which size classes are full / hotstats slabs — состояние slab-аллокатора
stats slabs раскрывает раскладку slab-аллокатора: у каждого класса есть chunk_size (до него округляются слоты элементов), chunks_per_page, total_pages и used/free chunks. Память, отданная классу, остаётся в нём и не возвращается другим классам. Если один класс переполнен и вытесняет элементы, а другой пуст, это slab-кальцификация; помогает настройка -f (коэффициент роста).
# memory layout of each slab class
stats slabs
# STAT 1:chunk_size 96
# STAT 1:chunks_per_page 10922
# STAT 1:total_pages 1
# STAT 1:total_chunks 10922
# STAT 1:used_chunks 100
# STAT 1:free_chunks 10822
# STAT 2:chunk_size 120
# ...
# STAT active_slabs 5
# STAT total_malloced 16777216
# END
# chunk_size -> bytes per item slot in this class
# total_chunks -> total slots
# used_chunks -> slots holding data
# free_chunks -> empty slotsstats sizes — гистограмма размеров
stats sizes строит гистограмму реальных размеров элементов (ключ+значение+накладные расходы), чтобы было видно, сколько памяти теряется на округление до размера чанка. Команда выполняет полное сканирование и исторически блокировала с ервер — в современных версиях она закрыта проверкой safe-mode; передайте --disable-safe-mode, чтобы принудительно запустить. Выполняйте только при низкой нагрузке. Вывод помогает выбрать правильный коэффициент роста -f.
# histogram of actual item sizes (key + value + overhead)
# WARNING: this command locks the cache while scanning — do NOT run
# in production at peak. Use stats sizes --disable-safe-mode only
# if you accept the risk.
stats sizes
# STAT 96 100 # 100 items rounded up to 96 bytes
# STAT 120 250
# STAT 192 50
# ...
# END
# compare to stats slabs to see how much memory is wasted to
# chunk-size rounding (internal fragmentation)stats cachedump — просмотр slab-класса
stats cachedump перечисляет ключи в заданном slab-классе (до N записей) и полезен для точечной отладки. Он обходит LRU-список класса и может быть медленным или вовсе отключённым в некоторых сборках — никогда не используйте его для перечисления ключей в продакшене. Memcached намеренно не даёт эффективного способа перечислить все ключи: считайте его чёрным ящиком, адресуемым вашим приложением.
# peek at keys in a specific slab class
# syntax: stats cachedump <slab_id> <limit> [noreply]
stats cachedump 1 10
# ITEM user:1 [5 b; 1700000000 s]
# ITEM user:2 [5 b; 1700000000 s]
# ...
# END
# WARNING: for debugging only — it walks the LRU and can be slow.
# Not all builds ship cachedump; it is disabled in some distros.
# Each ITEM shows: key, [value size in bytes; storage time s]
# do NOT use this for key enumeration in production code —
# memcached has no efficient SCAN commandstats reset и другие подкоманды
stats reset обнуляет накопленные счётчики (операции, попадания, промахи), не удаляя данные, — удобно, чтобы измерить свежий интервал после деплоя. Другие полезные подк оманды: stats settings (действующая конфигурация), stats conns (детали по соединениям в новых сборках), stats lru_crawler (состояние обходчика). В остальном счётчики накапливаются с момента запуска процесса, поэтому обнуляйте их перед бенчмарком.
# zero the cumulative counters (cmd_get, hits, misses, etc.)
stats reset
# -> RESET
# useful stats subcommands:
stats settings # current effective configuration
stats items # per-slab item counts/age
stats slabs # slab allocator layout
stats sizes # item size histogram (slow!)
stats conns # per-connection info (newer builds)
stats lru_crawler # crawler state
# reset counters after a deploy to measure only current run
# (counters are since process start otherwise)Настройки и конфигурация
stats settings — действующая конфигурация
stats settings показывает работающую конфигурацию: maxbytes (-m), maxconns (-c), growth_factor (-f), item_size_max (-I), включены ли вытеснение и CAS, а также состояние LRU-обходчика. Большинство этих параметров фиксируются при старте, и лишь немногие меняются на лету. Это первое место, где можно убедиться, что сервер действительно подхватил те флаги, которые вы думали.
# view the server's current effective settings
stats settings
# STAT maxbytes 67108864
# STAT maxconns 1024
# STAT tcpport 11211
# STAT udpport 0
# STAT inter NULL
# STAT evictions on
# STAT cas_enabled on
# STAT chunk_size 48
# STAT growth_factor 1.25
# STAT item_size_max 1048576
# STAT lru_crawler on
# ...
# END
# this reflects flags passed at startup (-m, -c, -f, -I, ...)Флаги запуска
Большая часть настройки выполняется флагами запуска. Критичные из них: -m (память), -l (всегда привязывайтесь к 127.0.0.1 или приватной сети — никогда не выставляйте Memcached в публичный интернет), -c (лимит соединений), -I (максимальный размер элемента) и -f (коэффициент роста slab). Флаг -M меняет поведение при переполнении на ошибку вместо LRU-вытеснения (для кеша нужно редко). Подбирайте -t под число ядер CPU для пропускной способности.
# common memcached startup flags
memcached -d -m 256 -p 11211 -u memcache -c 2048 -f 1.25 -I 1m
# -d run as a daemon
# -m <MB> max memory to use for items (default 64)
# -M return error instead of evicting when memory full
# -c <conn> max simultaneous connections (default 1024)
# -p <port> TCP port (default 11211)
# -U <port> UDP port (0 disables; default 11211)
# -l <addr> listen address (default all — bind to 127.0.0.1!)
# -u <user> run as this user (when started as root)
# -f <factor> slab growth factor (default 1.25)
# -n <bytes> min item allocation (default 48)
# -I <size> max item size (default 1m, can be 1m-1g)
# -t <threads> worker threads (default 4)
# -v / -vv / -vvv verbosityКонфигурация во время работы
Memcached даёт лишь несколько настроек на лету: cache_memlimit (изменить лимит памяти), семейство lru_crawler (включить/выключить/настроить фоновое удаление), verbosity (уровень логов) и flush_all (инвалидировать все элементы, возможно с задержкой). Большинство настроек фиксируются при старте: чтобы изменить -m, -c или -I, процесс перезапускают. flush_all — операция управления, а не настройка.
# a small number of settings can change at runtime:
# change the memory limit (bytes) live
cache_memlimit 536870912 # 512 MB
# -> OK
# LRU crawler controls
lru_crawler enable # turn the crawler on
lru_crawler disable # turn it off
lru_crawler sleep 100 # us between slab visits
lru_crawler tocrawl 1000 # max items per slab per pass
lru_crawler metadump all # dump key metadata (not values)
# log verbosity at runtime
verbosity 2
# flush_all (invalidate everything, not a config change)
flush_all
flush_all 900 # invalidate in 900 secondsРазбор важных настроек
-m — главная настройка: задавайте её под рабочий набор плюс запас, поскольку занижение ведёт к вытеснениям и постоянной прокрутке кеша. -f балансирует гранулярность slab-классов и внутреннюю фрагментацию: понижайте её (к 1.1), если у вас много элементов близких размеров. -I ограничивает размер элемента, по днимайте только при необходимости кешировать крупные объекты. -M для кеша нужен редко: он превращает нехватку памяти в ошибки вместо вытеснения.
# -m memory budget
# the single most important knob. Size to fit your working set
# with headroom; undersizing = evictions = cache churn.
#
# -f slab growth factor (default 1.25)
# smaller (1.1) = more slab classes, less internal fragmentation
# but more per-class memory stuck. Larger (1.5) = fewer classes,
# more waste per chunk.
#
# -I max item size (default 1m)
# raise to cache bigger blobs (e.g. -I 4m) at the cost of larger
# worst-case allocations.
#
# -M disable LRU eviction (error instead) — only for strict caches
#
# -t worker threads (default 4) — scale to CPU count for throughputЛимиты соединений и потоки
-c ограничивает число одновременных соединений — ставьте его с запасом выше (размер пула × число экземпляров приложения), иначе клиенты будут получать отказ (следите за listen_disabled_num в stats). -t задаёт рабочие потоки; Memcached событийно-ориентирован в каждом потоке, поэтому масштабируйте -t по числу ядер CPU, обычно 4–8. Дальше конкуренция за блокировки ограничивает выигрыш. Каждый поток владеет частью хеш-таблицы, так что больше потоков не помогают одному горячему ключу.
# -c max client connections (default 1024)
memcached -c 4096
# each connection costs a bit of memory; set -c above your expected
# peak concurrent clients (pool size * app instances + headroom)
# -t worker threads (default 4)
memcached -t 8
# memcached is event-driven per thread; each thread runs its own
# event loop and owns a slice of the hash table. Scale -t to CPU
# cores. Beyond ~8 threads, contention often limits gains.
# check connection pressure:
stats
# STAT curr_connections 412
# STAT total_connections 10230
# STAT listen_disabled_num 0 # >0 means you hit -c and refused connsСтратегии кеширования
Cache-Aside (ленивая загрузка)
Cache-aside — простейший и самый популярный шаблон: приложение сначала читает кеш, а при промахе загружает данные из БД и заполняет кеш обратно. Он устойчив (отказ кеша означает лишь рост нагрузки на БД), но допускает лавины на холодных ключах и устаревание до явной инвалидации. Всегда задавайте TTL даже при инвалидации на запись — как страховку от пропущенной инвалидации.
# the most common pattern — app manages the cache explicitly
def get_user(id):
key = "user:" + str(id)
val = mc.get(key) # 1) try cache
if val is not None:
return val # hit
val = db.query(id) # 2) miss -> load from DB
mc.set(key, val, ttl=3600) # 3) back-fill the cache
return val
# on write:
def update_user(id, data):
db.update(id, data)
mc.delete("user:" + str(id)) # invalidate (or set fresh value)
# pros: simple, resilient to cache failure
# cons: stampede on miss; stale until invalidatedRead-Through
В read-through сам слой кеша вызывает загрузчик при промахе — приложение просто делает get и получает значение. Это централизует логику заполнения кеша и гарантирует согласованность между вызывающими сторонами, ценой синхронного чтения из БД внутри вызова кеша. Большинство клиентов Memcached не поддерживают read-through из коробки, п оэтому обычно его реализуют тонкой обёрткой над cache-aside.
# the cache itself is responsible for loading from the DB
# (the client library or a cache layer provides a loader callback)
mc = memcached_with_loader(load_fn=db.query_user)
def get_user(id):
# the cache calls load_fn(id) automatically on a miss
return mc.get_or_load("user:" + str(id))
# pros:
# - app code is simpler (no miss-handling logic)
# - cache population is consistent across callers
# cons:
# - the cache library must support a loader (or you wrap it)
# - a cache miss is slower (synchronous DB read inside get)Write-Through
Write-through обновляет кеш при каждой записи, сохраняя его свежим без отдельного пути инвалидации. Цена — задержка записи (кеш + БД) и риск порядка при сбоях: если писать сначала в кеш, а запись в БД не удастся, в кеше окажутся недолговечные данные; если сначала в БД, появляется окно устаревания. Многие приложения сочетают write-through для горячих ключей с cache-aside для остальных.
# every write goes to the cache AND the DB synchronously
def update_user(id, data):
mc.set("user:" + str(id), data, ttl=3600) # cache first
db.update(id, data) # then DB
# or DB first, then cache — pick an order and stick with it
# pros:
# - cache stays fresh after writes (no stale reads)
# - no invalidation logic needed
# cons:
# - write latency = cache write + DB write
# - if the DB write fails after the cache write, cache is inconsistent
# - cache holds data even if never read (wastes memory)Write-Behind (Write-Back)
Write-behind немедленно пишет в кеш и асинхронно сохраняет в БД через очередь — задержка записи меньше миллисекунды и всплески сглаживаются. Цена — согласованность (БД отстаёт от кеша) и долговечность (падение до обработки очереди теряет данные). Один Memcached так не умеет: нужны очередь и воркер. Оставьте это для нагрузок с интенсивной записью, терпимых к потерям, — счётчиков и телеметрии.
# writes go to the cache first; DB is updated ASYNCHRONOUSLY later
# (memcached alone can't do this — it's a cache, not a queue.
# this pattern needs a worker/queue alongside it.)
def update_user(id, data):
mc.set("user:" + str(id), data, ttl=3600)
queue.push({"op":"update","id":id,"data":data}) # async DB write
# a background worker drains the queue to the DB
# pros:
# - very fast writes (cache-only latency)
# - absorbs write spikes
# cons:
# - DB lags behind cache -> reads may see newer data than DB
# - data loss if cache evicts/evacuates before the worker runs
# - complex (queue + worker + reconciliation)Инвалидация кеша
Инвалидация — самая сложная часть кеширования. Явный delete при записи — база; TTL — страховка (всегда задавайте его). Для коллекций, которые нельзя перечислить, используйте версионированные ключи (user:1:v42) и повышайте версию при изменении схемы или данных, чтобы старые записи вытеснялись. Ключи с временными корзинами (report:2024-01-01) истекают по дате. Никогда не пытайтесь инвалидировать по маске — Memcached не умеет перечислять ключи.
# invalidation is HARD — "there are only two hard problems in CS"
# 1) explicit invalidation on write
def update_user(id, data):
db.update(id, data)
mc.delete("user:" + str(id)) # drop stale entry
# 2) versioned keys to avoid invalidation entirely
key = "user:" + str(id) + ":v" + str(version)
# bump version on update -> old keys auto-expire via TTL
# 3) TTL as a safety net — even with explicit invalidation, set a TTL
# so a missed invalidation self-heals within (e.g.) an hour
# 4) namespacing by time/date for time-bucketed data
key = "report:" + today_date() # yesterday auto-expires
# anti-pattern: trying to invalidate "all user:* keys" —
# memcached can't enumerate keys, so use a versioned namespace insteadСтратегии TTL и вытеснения
Сопоставляйте TTL с изменчивостью данных: часы для справочников, минуты для пользовательских данных, длина окна для счётчиков rate limiting. Всегда добавляйте разброс (±5–10%), чтобы избежать синхронной лавины истечений. Memcached вытесняет LRU внутри slab при нехватке памяти, без закрепления отдельных элементов — единственные рычаги это TTL и общий размер. Для горячих ключей используйте блокировку на add, чтобы при промахе пересчитывал только один клиент.
# choose TTL by data volatility:
# reference data (rarely changes) -> 1-24 hours
# user data (changes on action) -> 5-60 minutes
# computed reports -> matches refresh cadence
# sessions -> matches idle timeout
# rate-limit counters -> matches the window (60s)
# add jitter to prevent synchronized expiry / stampedes:
ttl = base + random.randint(-60, 60)
# on high memory pressure, Memcached evicts LRU items per slab.
# to AVOID eviction of critical data, give it a longer TTL OR
# store it under a key pattern you can pin (memcached has no
# explicit "no-evict" flag — TTL + sizing are your tools).
# stampede protection: lock-and-recompute on miss
if mc.add("lock:user:1", "1", ttl=30):
val = db.query(1); mc.set("user:1", val, 3600); mc.delete("lock:user:1")
else:
val = mc.get("user:1") # another client is refreshing; retry shortlyКлиентские библиотеки
Python (pymemcache)
pymemcache — чистый Python, быстрый и явный. Используйте Client для одного сервера и HashClient для кластера с согласованным хешированием. set/get — базовые операции; get_many делает пакетный multi-get. Для счётчиков берите add+incr, для оптимистичных обновлений — gets/cas. Всегда задавайте таймауты: мёртвый узел должен быстро отказывать, а не подвешивать поток запроса.
# pip install pymemcache
from pymemcache.client.base import Client
mc = Client(("127.0.0.1", 11211), connect_timeout=2, timeout=1)
mc.set("user:1", "alice", expire=3600)
print(mc.get("user:1")) # b"alice"
# multi-get (batched)
for k, v in mc.get_many(["user:1", "user:2", "user:3"]).items():
print(k, v)
# counter
mc.add("views", 0)
mc.incr("views", 1)
# CAS loop
while True:
val, cas = mc.gets("counter")
if mc.cas("counter", int(val) + 1, cas, expire=0):
break
# use a consistent-hashing cluster
from pymemcache.client.hash import HashClient
cluster = HashClient([("mc1", 11211), ("mc2", 11211), ("mc3", 11211)])Node.js (memcached)
Пакет memcached для npm поддерживает один и несколько серверов (согласованное хеширование), пулы соединений и повторы. set/get/getMulti (пакетный multi-get) покрывают основной путь. Настройте poolSize под конкурентность и всегда задавайте таймаут, чтобы мёртвый узел быстро отказывал. Библиотека использует колбэки: оберните её в Promise или примените util.promisify для async/await.
// npm install memcached
const Memcached = require("memcached");
const mc = new Memcached("127.0.0.1:11211", {
timeout: 1000,
retries: 1,
poolSize: 10,
});
mc.set("user:1", "alice", 3600, (err) => {
if (err) console.error(err);
});
mc.get("user:1", (err, data) => {
console.log(data); // "alice"
});
// multi-get
mc.getMulti(["user:1", "user:2"], (err, data) => {
console.log(data["user:1"]);
});
// counter
mc.incr("views", 1, (err, val) => console.log(val));
// cluster: pass a comma-separated list, client does consistent hashing
const cluster = new Memcached("mc1:11211,mc2:11211,mc3:11211");
mc.end(); // close connections on shutdownPHP (расширение memcached)
Расширение memcached для PHP (на базе libmemcached) — выбор для продакшена: ставьте OPT_LIBKETAMA_COMPATIBLE для согласованного хеширования между серверами и addServers для кластера. getMulti делает пакетные чтения. cas() принимает токен из массива результата fetch(). Избегайте старого расширения memcache (без «d»): в нём меньше возможностей и оно хуже поддерживается. Всегда задавайте TTL и аккуратно обрабатывайте Memcached::RES_NOTFOUND.