Primeiros Passos
Conectar e Comandos Básicos
Memcached usa um protocolo de texto simples na porta 11211. O comando set recebe flags (um inteiro de 32 bits opaco ao servidor), exptime (expiração em segundos, 0 = sem expiração) e tamanho em bytes. Os valores são guardados como bytes crus — o servidor nunca os inspeciona nem os modifica. memcached-tool vem com o servidor e é prático para estatísticas rápidas.
# 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 mykeyVisão Geral do Protocolo
Memcached suporta tanto um protocolo de texto ASCII (fácil de usar com telnet/netcat) quanto um protocolo binário (mais eficiente, suporta autenticação SASL e operações atômicas). O protocolo binário usa um header fixo de 24 bytes e é o preferido da maioria dos clientes de produção. Ambos os protocolos operam no mesmo armazenamento chave-valor subjacente.
# 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.24Regras e Limites de Chaves
As chaves são limitadas a 250 bytes e não podem conter espaços nem caracteres de controle no protocolo de texto. O tamanho máximo padrão de valor é 1MB (aumente com a flag -I, ex.: -I 4m). As chaves não são copiadas — o Memcached as guarda inline, então chaves mais longas consomem mais memória. Use chaves curtas e estruturadas como user:1001 em vez de nomes descritivos verbosos.
# 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 4mCasos de Uso Comuns
Memcached é melhor para cachear dados transitórios e derivados: resultados de consultas de banco, sessões, fragmentos de página renderizados, contadores de limite de taxa e cálculos caros. É intencionalmente simples — sem persistência, sem replicação, sem tipos de dados complexos. Trate-o como um cache LRU volátil: nunca guarde dados que você não consiga reconstruir a partir de um sistema de registro.
# 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}Visão Geral da Arquitetura
Memcached é um cache distribuído feito de servidores independentes e não coordenados. Não há clustering, replicação nem failover no próprio servidor — toda a lógica de distribuição vive no cliente (hashing consistente). Cada nó possui uma fatia disjunta do keyspace; se um nó morre, seus dados se perdem e os clientes redirecionam. Isso mantém o servidor extremamente simples e rápido, ao custo da durabilidade.
# 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 serverComandos Básicos (set / get / delete)
set — Guardar um Valor
set guarda um valor incondicionalmente, sobrescrevendo qualquer chave existente. flags é um inteiro de 32 bits que o servidor guarda mas nunca interpreta — clientes o usam para codificar o formato de serialização (ex.: 1 = JSON, 2 = comprimido). exptime 0 significa sem expiração; um timestamp Unix > 30 dias é tratado como tempo absoluto. noreply pula a resposta para escritas dispara-e-esquece (mais rápido, mas sem reporte de erros).
# 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 — Recuperar Valores
get recupera uma ou mais chaves numa única ida e volta — agrupar (multi-get) é crítico para o desempenho. Cada linha VALUE retornada ecoa as flags para que o cliente saiba como desserializar. Chaves ausentes são omitidas silenciosamente (sem erro). A resposta termina com END. Multi-gets grandes devem ser divididos em lotes para não monopolizar uma única thread do servidor.
# 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 — Recuperar com Token CAS
gets (get-estendido) é idêntico a get, mas acrescenta um token cas_unique a cada linha VALUE. Esse inteiro de 64 bits muda a cada escrita e é a fundação da concorrência otimista do Memcached (CAS). Use gets + cas juntos para evitar atualizações perdidas quando múltiplos clientes modificam a mesma chave. O token é opaco — nunca presuma seu valor ou monotonicidade entre chaves.
# 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 — Remover uma Chave
delete remove uma única chave, retornando DELETED ou NOT_FOUND. Não há deleção por curinga ou padrão — o Memcached não tem comando de enumeração de chaves de forma alguma, então a deleção em massa precisa ser acompanhada pela aplicação (mantenha um conjunto de chaves em outro lugar ou use padrões de flush com namespace). Adicione noreply para pular a resposta. A memória deletada retorna à sua slab e é reutilizada.
# 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 e gat — Atualizar Expiração
touch (1.4.8+) atualiza a expiração de uma chave sem transferir o valor — mais barato que get+set para renovar sessões. gat busca o valor e atualiza o TTL atomicamente numa única ida e volta, ideal para leituras de sessão que devem estender o tempo de vida. gats também retorna o token CAS. Use estes em vez de get+set para evitar uma corrida em que o valor muda entre as operações.
# 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_FOUNDComandos de Armazenamento (add / replace / append / prepend)
add — Guardar Só Se Não Existir
add guarda um valor só se a chave AINDA não existe, retornando NOT_STORED caso contrário. É a forma canônica de inicializar chaves preguiçosamente (contadores, locks) sem corrida. Combinado com incr/decr, forma um padrão de contador seguro: add para criar em 0, depois incr. Diferente do SETNX do Redis, add não tem atalho de TTL — defina exptime no comando.
# 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 — Guardar Só Se Existir
replace guarda um valor só se a chave JÁ existe — o espelho de add. Impede que um caminho de atualização velho crie acidentalmente uma entrada de cache. Retorna NOT_STORED quando a chave está ausente. Use quando uma escrita deve renovar o cache existente, mas nunca povoar uma entrada nova (ex.: uma renovação em segundo plano que não deve ressuscitar uma chave despejada).
# 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 — Anexar a um Valor Existente
append concatena dados ao fim de um valor existente, retornando NOT_STORED se a chave estiver ausente. Os argumentos flags e exptime são aceitos, mas ignorados — o valor mantém seus metadados originais. Ótimo para construir linhas de log ou buffers no próprio local, sem ler-modificar-escrever. Cuidado: o valor resultante ainda deve caber no limite de 1MB por item.
# 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 — Preceder um Valor Existente
prepend é o espelho de append — concatena dados ao INÍCIO de um valor existente. Como append, exige que a chave exista e ignora flags/exptime. Útil para empilhar headers/prefixos num valor bufferizado. append e prepend NÃO são leitura-modificação-escrita atômica entre clientes no sentido de não retornarem o resultado — mas são operações atômicas no lado do servidor.
# 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 changeComparação dos Comandos de Armazenamento
Os seis comandos de armazenamento do Memcached (set, add, replace, append, prepend, cas) diferem só na pré-condição para guardar. set é incondicional; add/replace são condicionados à existência; append/prepend modificam no local e ignoram metadados; cas é condicionado ao token CAS do gets. Escolher o certo transforma uma corrida de ler-modificar-escrever numa única operação atômica do servidor.
# 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 (Compare-And-Swap)
gets — Obter o Token CAS
gets (get-estendido) é a metade de leitura do CAS. Retorna o valor mais um token cas_unique de 64 bits que o servidor garante mudar a cada modificação daquela chave. Você captura esse token e o devolve ao cas; se o token ainda casar, sua escrita tem sucesso. Sem gets não é possível fazer um CAS seguro — um get simples omite o token.
# 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 — Escrita Condicional
cas escreve um valor só se o token cas_unique ainda casar com o que o gets retornou. STORED significa que a escrita foi aplicada; EXISTS significa que outro cliente modificou a chave primeiro (token divergente); NOT_FOUND significa que a chave foi deletada. Isso é lock otimista — repita o ciclo inteiro gets→modificar→cas no EXISTS. Evita atualizações perdidas sem travas no servidor.
# 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)Caso de Uso do CAS: Contador Seguro
CAS resolve o problema da atualização perdida quando você precisa de semântica de ler-modificar-escrever (ex.: atualizar um blob JSON dentro de uma entrada de cache). No EXISTS, você precisa reler com gets, reaplicar sua transformação e repetir o cas — tipicamente com uma contagem limitada de tentativas para evitar live-lock. Para contadores puramente inteiros, incr/decr são mais simples e atômicos; recorra ao CAS só quando o valor for estruturado.
# 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)Falha e Retry do CAS
Um loop CAS robusto precisa tratar três resultados: chave ausente (use add, recue para tentar de novo no NOT_STORED), token correspondente (STORED, pronto) e token divergente (EXISTS, repetir). Limite as tentativas para evitar live-lock sob contenção. Se a chave realmente está ausente, prefira add a set, para que dois clientes em corrida para criá-la não se estraguem mutuamente.
# 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")Limitações do CAS
CAS é só de chave única — Memcached não tem transações multi-chave como MULTI/EXEC do Redis. É otimista, não pessimista: sob contenção pesada, muitas escritas vão bater no EXISTS e repetir, então fragmente chaves quentes. O cas_unique é por chave e opaco; nunca o compare entre chaves nem presuma ordenação. Se uma chave é despejada e recriada, o token reseta, então trate NOT_FOUND como um recomeço, não uma falha.
# 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)Contadores (incr / decr)
incr — Incremento Atômico
incr soma atomicamente um inteiro positivo a uma chave cujo valor é uma string decimal, retornando o novo valor. A operação é totalmente atômica entre clientes concorrentes — sem atualizações perdidas. O valor deve ser ASCII numérico sem sinal de 64 bits (sem sinais, sem decimais). incr numa chave ausente retorna NOT_FOUND; em dados não numéricos, dá erro. Não há auto-criação — use add primeiro.
# 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 — Decremento Atômico
decr subtrai atomicamente de um valor numérico e retorna o resultado. É limitado a zero no mínimo — nunca produz um número negativo, o que é conveniente para contadores de estoque/inventário, mas significa que não se pode usar decr para acompanhar saldos líquidos negativos. Como incr, exige que o valor seja dígitos ASCII e que a chave exista (senão 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_ERRORInicializando Contadores
Como incr/decr retornam NOT_FOUND numa chave ausente, os contadores precisam ser inicializados com add (sem corrida: o primeiro chamador cria em 0, os outros recebem NOT_STORED e passam direto ao incr). Nunca use set para inicializar um contador que você também incrementa — set sobrescreve incondicionalmente e corre contra incrementos concorrentes. Nomeie contadores por data e defina um TTL para que expirem sozinhos.
# 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-02Casos de Uso de Contadores
Contadores brilham para limitação de taxa (chave por IP+minuto com TTL de 60s), estatísticas de visualização/download, contagens de ativos diários, inventário e métricas de lançamento. São atômicos e baratos, então escalam para taxas de escrita muito altas. Para limitação de taxa, escolha uma granularidade de chave (por usuário, por IP) e um TTL que casem com sua janela — e lembre que decr limita em 0, então o estoque não pode ficar negativo.
# 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 1Limitações de Contadores
Contadores são só inteiros de 64 bits sem sinal — sem floats, sem negativos, sem sinais. incr/decr nunca criam uma chave automaticamente. decr limita em 0. Como o valor é só uma string, um set/replace perdido vai sobrescrevê-lo e estragar incrementos concorrentes — inicialize com add e, fora isso, use sempre incr/decr. Para floats ou contadores multi-campo, use CAS num valor estruturado.
# 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 racesExpiração e TTL
set com Expiração
exptime está em segundos: 0 significa nunca expirar, valores até 2592000 (30 dias) são TTLs relativos, e valores maiores são interpretados como timestamps Unix absolutos. Itens expirados não são recolhidos ativamente no segundo exato — o Memcached usa expiração preguiçosa (verificada no acesso) mais um rastejador LRU em segundo plano, então uma chave velha pode persistir até ser tocada ou despejada.
# 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 — Atualizar TTL
touch (1.4.8+) atualiza o TTL de uma chave no próprio local sem transferir o valor — muito mais barato que get+set para sessões de janela deslizante. Defina exptime como 1 para soft-delete (vira imediatamente expirado). A mesma regra de relativo-vs-absoluto de 30 dias vale. touch retorna NOT_FOUND para chaves ausentes, então os chamadores devem tratar isso como 'não cacheado'.
# 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 e gats — Get e Touch
gat (1.6+) combina get e touch atomicamente numa única ida e volta — perfeito para leituras de sessão que devem adiar a expiração. gats também retorna o token CAS. Usar get+touch separadamente cria uma janela em que o TTL não é renovado e dobra as idas e voltas; gat corrige ambas. Para leituras deslizantes multi-chave, gat aceita várias chaves.
# 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 cComportamento de Expiração
A expiração no Memcached é preguiçosa por padrão — uma chave só é recolhida quando acessada, o que significa que dados velhos podem ocupar memória até serem despejados. O LRU crawler (1.4.24+) adiciona uma varredura em segundo plano que libera proativamente itens expirados por slab, prevenindo desperdício de memória. Habilite em produção: lru_crawler enable. Mesmo assim, nunca confie em timing preciso de expiração para correção.
# 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)Boas Práticas de TTL
Sempre defina um TTL — entradas de cache ilimitadas causam crescimento de memória ilimitado e bugs de dados velhos. Adicione jitter aleatório (±5-10%) aos TTLs para que expirações correlacionadas não causem avalanche na origem. Nomeie dados voláteis por data para que entradas antigas expirem sozinhas. Num miss, recompute e guarde no mesmo caminho de código para manter o cache quente. Use delete, não TTL=1, para invalidação explícita.
# 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 deleteComandos de Estatísticas
stats — Visão Geral
stats despeja as métricas centrais do servidor: cmd_get/cmd_set (ops totais), get_hits/get_misses (taxa de acerto = hits/cmd_get), evictions (itens descartados por pressão de memória), curr_items, bytes vs limit_maxbytes e contagens de conexão. Taxa de acerto e evictions são os dois números a vigiar primeiro. Esta é a fundação de qualquer monitoramento de 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 — Contagens por Slab
stats items reporta, para cada classe de slab, quantos itens guarda (number) e a idade do item menos recentemente guardado (age). Um slab com number alto e age baixa está sendo chacinado; um slab com age alta guarda dados de vida longa. É o primeiro lugar a olhar ao ajustar tamanhos de chunk ou diagnosticar por que uma faixa de tamanho específica está sendo despejada.
# 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 — Estado do Alocador de Slabs
stats slabs revela o layout do alocador de slabs: cada classe tem um chunk_size (os slots de itens são arredondados para ele), chunks_per_page, total_pages e chunks usados/livres. Memória atribuída a uma classe de slab fica lá — não pode voltar para outras classes. Se uma classe está cheia e despejando enquanto outra está vazia, você tem calcificação de slab, endereçável com ajuste de -f (fator de crescimento).
# 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 — Histograma de Tamanhos
stats sizes constrói um histograma de tamanhos reais de itens (chave+valor+custo extra), para que você veja quanta memória se perde ao arredondar para o tamanho de chunk. Ele faz uma varredura completa e historicamente travava o servidor — versões modernas o condicionam a uma checagem de modo seguro; passe --disable-safe-mode para forçar. Rode só em tráfego baixo. A saída ajuda a escolher o fator de crescimento -f certo.
# 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 — Inspecionar um Slab
stats cachedump lista as chaves guardadas numa dada classe de slab (limitada a N entradas), útil para depuração ad hoc. Percorre o LRU do slab e pode ser lento ou totalmente desativado em alguns builds — nunca use para enumeração de chaves em produção. O Memcached deliberadamente não oferece forma eficiente de listar todas as chaves; trate-o como caixa preta indexada pela sua aplicação.
# 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 e Outros Subcomandos
stats reset zera os contadores cumulativos (ops, hits, misses) sem perder dados — prático para medir um intervalo novo após um deploy. Outros subcomandos úteis: stats settings (config efetiva), stats conns (detalhe por conexão em builds novos), stats lru_crawler (estado do rastejador). Fora isso, os contadores são cumulativos desde o início do processo, então resete antes de medir desempenho.
# 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)Configurações e Configuração
stats settings — Configuração Efetiva
stats settings mostra a configuração em execução: maxbytes (-m), maxconns (-c), growth_factor (-f), item_size_max (-I), se despejos e CAS estão habilitados e o estado do LRU crawler. A maioria é fixada na inicialização; só um punhado pode mudar em runtime. É o primeiro lugar para confirmar se seu servidor pegou as flags que você acha que pegou.
# 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, ...)Flags de Inicialização
A maioria da configuração acontece via flags de inicialização. As críticas: -m (memória), -l (sempre vincule a 127.0.0.1 ou uma rede privada — nunca exponha o Memcached publicamente), -c (limite de conexões), -I (tamanho máximo de item) e -f (fator de crescimento de slabs). -M inverte o comportamento de despejo para erro-quando-cheio em vez de despejo LRU (raramente desejado para um cache). Ajuste -t à sua contagem de CPUs para rendimento.
# 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 verbosityConfiguração em Runtime
O Memcached expõe só alguns controles de runtime: cache_memlimit (redimensionar o teto de memória ao vivo), a família lru_crawler (habilitar/desabilitar/ajustar o ceifador em segundo plano), verbosity (nível de log) e flush_all (invalidar cada um dos itens, opcionalmente com atraso). A maioria das configurações permanece fixa na inicialização — para mudar -m, -c ou -I, reinicie o processo. flush_all é uma operação de plano de controle, não uma configuração.
# 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 secondsConfigurações Importantes Explicadas
-m é a configuração de manchete: dimensione-o ao seu working set mais folga, já que subdimensionar causa despejos e churn de cache. -f troca a granularidade das classes de slab por fragmentação interna — reduza-o (rumo a 1.1) quando tiver muitos itens de tamanho estreito. -I limita o tamanho do item; aumente só se precisar cachear blobs grandes. -M é raramente usado para cache — transforma OOM em erros em vez de despejos.
# -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 throughputLimites de Conexões e Threads
-c limita conexões concorrentes — defina-o confortavelmente acima de (tamanho_do_pool × instâncias_do_app) ou os clientes serão recusados (vigie listen_disabled_num nas stats). -t define threads de trabalho; o Memcached é dirigido a eventos por thread, então escale -t para os núcleos de CPU, tipicamente 4-8. Além disso, a contenção de travas limita os ganhos. Cada thread possui uma fatia da tabela hash, então mais threads não ajudam uma única chave quente.
# -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 connsEstratégias de Cache
Cache-Aside (Carregamento Preguiçoso)
Cache-aside é o padrão mais simples e popular: o app lê o cache primeiro e, num miss, carrega do banco e retroalimenta o cache. É resiliente (uma indisponibilidade do cache só significa mais carga no banco), mas permite avalanches em chaves frias e obsolescência até a invalidação explícita. Sempre defina um TTL mesmo ao invalidar na escrita, como rede de segurança para invalidações perdidas.
# 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
No read-through, a própria camada de cache invoca um loader num miss — o app apenas chama get e recebe um valor. Isso centraliza a lógica de preenchimento do cache e garante consistência entre chamadores, ao custo de uma leitura síncrona do banco dentro da chamada de cache. A maioria dos clientes Memcached não traz read-through embutido, então costuma ser implementado como um wrapper fino sobre 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
O write-through atualiza o cache a cada escrita, mantendo-o fresco sem caminho separado de invalidação. A troca é a latência de escrita (cache + banco) e um risco de ordenação de falhas: se você escreve cache-primeiro e a escrita no banco falha, o cache guarda dados que não são duráveis; escrevendo banco-primeiro, há uma janela de obsolescência. A maioria dos apps combina write-through para chaves quentes com cache-aside para o resto.
# 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)
O write-behind escreve no cache imediatamente e persiste no banco de forma assíncrona via fila — dando latência de escrita sub-milissegundo e absorção de picos. O custo é consistência (o banco atrasa em relação ao cache) e durabilidade (um crash antes do worker drenar perde dados). O Memcached sozinho não faz isso; você precisa de fila + worker. Reserve para cargas de muita escrita e tolerantes a perdas, como contadores e telemetria.
# 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)Invalidação de Cache
A invalidação é a parte mais difícil do cacheamento. Deletar-na-escrita explícito é a linha de base; o TTL é a rede de segurança (sempre defina um). Para coleções que você não consegue enumerar, use chaves versionadas (user:1:v42) e incremente a versão em mudanças de schema/dados, para que entradas velhas envelheçam. Chaves por intervalo de tempo (report:2024-01-01) expiram sozinhas pela data. Nunca tente invalidação por curinga — o Memcached não lista chaves.
# 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 insteadEstratégias de TTL e Despejo
Case o TTL à volatilidade dos dados: horas para dados de referência, minutos para dados de usuário, o comprimento da janela para contadores de limite de taxa. Sempre adicione jitter (±5-10%) para evitar avalanches de expiração sincronizada. O Memcached despeja por LRU por slab sob pressão de memória, sem fixação por item — as únicas alavancas são o TTL e o dimensionamento total. Para chaves quentes, use um lock baseado em add, para que só um cliente recompute num miss.
# 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 shortlyBibliotecas Cliente
Python (pymemcache)
pymemcache é Python puro, rápido e explícito. Use o Client simples para um servidor único e HashClient para um cluster com hashing consistente. set/get são o básico; get_many agrupa um multi-get. Use add+incr para contadores e gets/cas para atualizações otimistas. Sempre passe timeouts explícitos — um nó morto deve falhar rápido, não pendurar sua thread de requisição.
# 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)
O pacote npm memcached suporta setups de servidor único e múltiplo (hashing consistente), pooling de conexões e retries. set/get/getMulti (multi-get em lote) cobrem o caminho comum. Configure poolSize à sua concorrência e sempre defina um timeout para que um nó morto falhe rápido. A biblioteca é estilo callback; embrulhe em Promises ou use util.promisify para ergonomia 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 (extensão memcached)
A extensão memcached do PHP (construída sobre libmemcached) é a escolha de produção — defina OPT_LIBKETAMA_COMPATIBLE para hashing consistente entre servidores, e addServers para um cluster. getMulti agrupa leituras. cas() recebe o token do array de resultado do fetch(). Evite a extensão memcache mais antiga (sem o 'd'); faltam-lhe recursos e é menos mantida. Sempre defina TTLs e trate Memcached::RES_NOTFOUND com elegância.
<?php
// requires the memcached extension (libmemcached-based)
$mc = new Memcached();
$mc->addServer("127.0.0.1", 11211);
$mc->set("user:1", "alice", 3600);
echo $mc->get("user:1"); // alice
// multi-get returns associative array
$rows = $mc->getMulti(["user:1", "user:2", "user:3"]);
// counter
$mc->set("views", 0);
$mc->increment("views", 1);
// CAS
$mc->getDelayed(["counter"], false, null);
while ($item = $mc->fetch()) {
$cas = $item["cas"];
$mc->cas($cas, "counter", intval($item["value"]) + 1);
}
// cluster with consistent hashing
$mc->setOption(Memcached::OPT_LIBKETAMA_COMPATIBLE, true);
$mc->addServers([
["mc1", 11211],
["mc2", 11211],
["mc3", 11211],
]);Ruby (dalli)
Dalli é o cliente Memcached canônico do Ruby — Ruby puro, thread-safe e o armazenamento de cache padrão do Rails. Passe um array de servidores para clustering com hashing consistente (ketama). Sua forma de bloco cas relê e repete automaticamente em conflito, muito mais ergonômica que loops manuais. Configure expires_in globalmente e sobrescreva por chamada para TTLs mais apertados.
# gem install dalli
require "dalli"
# single server
mc = Dalli::Client.new("127.0.0.1:11211", { expires_in: 3600 })
mc.set("user:1", "alice")
mc.get("user:1") # => "alice"
# multi-get (returns a hash)
mc.get_multi(["user:1", "user:2", "user:3"])
# counter
mc.incr("views", 1)
mc.decr("views", 1)
# CAS
mc.get("counter") do |val, cas|
mc.cas("counter", cas) { val.to_i + 1 }
end
# cluster with consistent hashing (ketama)
cluster = Dalli::Client.new(["mc1:11211", "mc2:11211", "mc3:11211"],
{ expires_in: 3600 })Java (spymemcached)
spymemcached é um cliente Java assíncrono, baseado em NIO e de alto desempenho. Sua API é baseada em Future; get() bloqueia quando você precisa de confirmação. Passe uma lista de servidores separada por espaços ao AddrUtil para hashing consistente. gets()/cas() fornecem concorrência otimista, e getBulk() faz um multi-get em lote. Sempre shutdown() ao desmontar o app para liberar as threads de I/O.
// build.gradle: implementation 'net.spy:spymemcached:2.12.3'
import net.spy.memcached.MemcachedClient;
import net.spy.memcached.AddrUtil;
MemcachedClient mc = new MemcachedClient(
AddrUtil.getAddresses("mc1:11211 mc2:11211 mc3:11211"));
// async API returns java.util.concurrent.Future
Future<Boolean> f = mc.set("user:1", 3600, "alice");
f.get(); // block for confirmation
Object val = mc.get("user:1"); // "alice"
// counter
mc.incr("views", 1);
// CAS
CASValue<Object> cv = mc.gets("counter");
CASResponse r = mc.cas("counter", cv.getCas(), newVal);
if (r == CASResponse.OK) { /* success */ }
// bulk get
Map<String, Object> rows = mc.getBulk("user:1", "user:2", "user:3");
mc.shutdown();Go (gomemcache)
gomemcache (bradfitz) é o cliente Go de facto — simples, rápido e suporta hashing consistente entre múltiplos servidores. Set/Get recebem uma struct Item que agrupa chave, valor, TTL e o token CAS; CompareAndSwap faz a atualização otimista. GetMulti retorna um map indexado por nome (chaves ausentes estão ausentes, não são erros). É seguro para concorrência; reutilize um cliente entre goroutines.
// go get github.com/bradfitz/gomemcache/memcache
import memcache "github.com/bradfitz/gomemcache/memcache"
mc := memcache.New("mc1:11211", "mc2:11211", "mc3:11211")
// set
err := mc.Set(&memcache.Item{
Key: "user:1", Value: []byte("alice"), Expiration: 3600,
})
// get
it, err := mc.Get("user:1")
// it.Value -> []byte("alice")
// multi-get (returns map, missing keys absent)
rows, _ := mc.GetMulti([]string{"user:1", "user:2"})
// counter
mc.Increment("views", 1)
mc.Decrement("views", 1)
// CAS
it, _ = mc.Get("counter")
it.Value = []byte("6")
it.Cas = it.Cas // use existing token
mc.CompareAndSwap(it)
// delete
mc.Delete("user:1")Arquitetura Distribuída
Hashing Consistente
O hashing consistente mapeia tanto servidores quanto chaves num anel; uma chave é possuída pelo próximo servidor no sentido horário. Adicionar ou remover um servidor move só a fatia de chaves daquele servidor (cerca de 1/N), não o keyspace inteiro — muito melhor que hash(chave) % N, que remapeia quase tudo a cada mudança de composição. A maioria dos clientes usa a variante ketama com muitos nós virtuais por servidor, para distribuição equilibrada.
# consistent hashing spreads keys across servers with minimal
# remapping when the pool changes.
#
# 1) hash each server onto a ring (multiple virtual nodes each)
# 2) hash the key, walk the ring clockwise to the next server
#
# ring: s1---s2---s3---s1
# ^ ^
# keyA keyB -> goes to s3
#
# adding s4 only moves keys between s3 and s4 (not the whole ring)
# removing s1 only moves keys between s1's predecessor and s2
#
# result: |keys moved| ~= keys/N when adding/removing one server
# (vs. ~all keys remapped with hash(key) % N)
# most clients implement ketama consistent hashing automatically
# when you pass a list of serversSharding no Cliente
o sharding inteiro vive no cliente: ele faz o hash de cada chave para um servidor e espalha multi-gets pelos servidores em paralelo. Cada chave existe em exatamente um nó — não há replicação, então um nó morto perde sua fatia do keyspace. Não há proxy nem coordenador; cada cliente deve compartilhar a mesma lista de servidores e config de hashing (ketama), senão as chaves caem em nós diferentes e causam misses em massa.
# memcached servers do NOT coordinate — sharding is 100% client-side.
#
# the client picks ONE server per key:
# server = ring[hash(key)]
#
# a multi-get is split across servers in parallel:
# getMulti(["a","b","c"])
# -> get "a" from mc1
# -> get "b" from mc2 (concurrent, fan-out)
# -> get "c" from mc1
#
# this means:
# - each key lives on exactly ONE server (no replication)
# - a multi-get touches multiple servers but returns one result set
# - the client must know the full server list (no proxy)
# never put a replica behind the same client as a primary for the
# same key range — memcached clients do not read-replicateAlgoritmos de Hashing (Ketama)
Ketama é o esquema canônico de hashing consistente do memcached: cada servidor físico é mapeado no anel como muitos nós virtuais (~160) para carga equilibrada. Localizar uma chave faz o hash dela e caminha no sentido horário até o próximo nó. A pegadinha crítica: cada cliente em toda linguagem deve usar o mesmo algoritmo e strings de rótulo de servidor idênticas, senão divergem na posse e causam misses de cache em massa após um deploy.
# ketama is the de-facto consistent-hashing algorithm for memcached.
#
# for each server, create N virtual nodes (default ~160-200):
# for i in range(vnodes):
# point = hash("server:port-" + i)
# ring[point] = server
#
# to locate a key:
# point = hash(key)
# server = first node clockwise from point on the ring
#
# benefits of many virtual nodes:
# - balanced load (no single server gets a huge arc)
# - smooth redistribution on add/remove
#
# IMPORTANT: all clients must use the SAME algorithm + server labels,
# or they will disagree on which server owns a key.
# enable in clients:
# PHP: Memcached::OPT_LIBKETAMA_COMPATIBLE
# Ruby: default in dalli
# Python: HashClient (pymemcache)Adicionando e Removendo Servidores
Com hashing consistente, adicionar ou remover um servidor remapeia só ~1/N das chaves — muito melhor que hashing por módulo, que remapeia quase tudo. Mas o crash de um servidor ainda perde permanentemente suas chaves (sem replicação), causando um pico transitório de carga na origem enquanto essas entradas se repovoam. Lance mudanças de composição para cada um dos clientes de uma vez, e considere pré-aquecer um nó novo sombreando leituras antes de entrar no ar.
# adding a server to the ring:
# - only ~1/N of keys remap (the slice the new server now owns)
# - those keys are cold misses until repopulated -> brief spike
#
# removing a server (e.g. crash):
# - that server's keys are GONE (no replication)
# - its slice of the ring is reassigned to neighbors
# - all reads to those keys miss until repopulated
#
# best practices for membership changes:
# 1) deploy new server list to all clients simultaneously
# 2) warm a new server with a shadow-read phase if possible
# 3) expect a transient increase in DB load (cache misses)
# 4) use weighted virtual nodes to add capacity gradually
# anti-pattern: hash(key) % N -> changes ALL key placements on
# every membership change (catastrophic for cache hit rate)Replicação e Failover
Memcached não tem replicação nem failover embutidos — um nó morto perde seus dados e os clientes redirecionam. Para adicionar redundância, ou você replica no cliente (escrever em N nós, mais custo), roda um proxy como mcrouter/twemproxy, ou aceita a perda e reconstrói a partir da origem. A escolha idiomática é a última: trate o cache como descartável, dimensione o pool para que a perda de um nó seja tolerável, e deixe os misses se reabastecerem do banco.
# memcached has NO built-in replication or failover.
# if a node dies, its data is gone — clients reroute to the ring.
#
# to ADD replication, options:
#
# 1) client-side replication: write to N servers per key
# - the client writes to primary + replica(s) on each set
# - reads try primary, fall back to replica
# - trade-off: N x write traffic + memory, weaker consistency
#
# 2) repcached: a memcached fork with master/replica replication
# - largely unmaintained today; avoid for new projects
#
# 3) use a layer above: twemproxy / mcrouter / mc-router
# - proxy that handles sharding, pooling, failover
#
# 4) accept the loss: cache is volatile by design — rebuild from DB
# the "memcached way" is usually option 4: don't replicate, just
# size the pool so a single node loss is survivableGestão de Memória (Slabs / LRU)
Alocador de Slabs
O Memcached usa um alocador de slabs: a memória é dividida em classes de chunks de tamanho fixo, e um item é guardado no menor chunk que couber (arredondado para cima). Isso evita fragmentação de malloc/free e dá alocação O(1), ao custo de fragmentação interna (espaço desperdiçado dentro dos chunks) e calcificação de classes (memória não pode se mover entre classes). É por isso que uma mistura uniforme de tamanhos de valor importa para a eficiência.
# memcached does NOT use malloc/free per item (that fragments).
# instead it pre-allocates fixed-size "slab classes" of chunks.
#
# slab class 1: chunks of 96 bytes
# slab class 2: chunks of 120 bytes
# slab class 3: chunks of 152 bytes (grow by -f factor)
# ...
#
# a 50-byte value -> rounded up to 96-byte chunk (class 1)
# a 100-byte value -> rounded up to 120-byte chunk (class 2)
#
# trade-offs:
# + no per-item malloc overhead, no heap fragmentation
# + O(1) alloc/free
# - internal fragmentation (wasted bytes inside a chunk)
# - memory is stuck per class (can't move between classes)
# inspect with:
stats slabsClasses de Slab e Fator de Crescimento
Os tamanhos das classes de slab começam no mínimo -n (padrão 48 bytes) e crescem pelo fator -f (padrão 1.25) até o tamanho máximo de item -I. Um -f menor rende mais classes de grão fino (menos desperdício, mais risco de calcificação de classes); um -f maior rende menos classes mais grossas (mais desperdício). Inspecione seu histograma real de tamanhos de valor com stats sizes e ajuste -f para que os tamanhos populares caiam em classes bem preenchidas.
# slab class sizes start at -n (default 48 bytes) and grow by -f:
#
# class 1: 48 bytes (base, -n)
# class 2: 48 * 1.25 = 60
# class 3: 60 * 1.25 = 75 -> 80
# class 4: 80 * 1.25 = 100
# ...
# up to the max item size (-I, default 1MB)
#
# -f default 1.25 balances class count vs. waste.
# lower (1.1) -> more classes, less waste, but more stuck memory
# higher (1.5) -> fewer classes, more waste per chunk
#
# tune -f to your value-size distribution (check stats sizes)
# example: many small JSON values -> -f 1.1 -n 80
memcached -m 512 -f 1.1 -n 80Despejo por LRU
O despejo é por classe de slab e estritamente LRU dentro dessa classe: quando uma classe enche, o item menos recentemente usado daquela classe é descartado para abrir espaço. Uma classe com chunks livres nunca despeja, então uma distribuição desequilibrada de tamanhos pode causar despejo pesado numa classe enquanto outra fica ociosa — o clássico problema de calcificação de slab. Vigie evictions e evicted_active nas stats para notar.
# when a slab class is full and a new item arrives in that class,
# memcached evicts the LEAST RECENTLY USED item in that class.
#
# eviction is PER-SLAB-CLASS, not global:
# - a full class-1 (96B) evicts class-1 items only
# - a class with free chunks never evicts
#
# this means an unbalanced workload can evict from one class
# while another class sits idle with free chunks.
#
# check eviction pressure:
stats
# STAT evictions 1234 # total items ever evicted
# STAT evicted_active 12 # evicted even though recently used (1.6+)
# STAT evicted_unfetched 50 # evicted before ever read
stats items
# STAT items:1:evicted 500 # evictions in slab class 1
# STAT items:1:outofmemory 0Limites de Memória (-m)
-m limita a memória de itens em MB; uma vez atingido, o Memcached para de adicionar páginas de slab e despeja por LRU dentro das classes. -M muda a política para erro-quando-cheio em vez de despejar (raramente desejável para um cache). cache_memlimit redimensiona o teto ao vivo. Dimensione -m ao seu working set com folga — rodar a 100% significa despejos constantes e um cache agitado, de baixa taxa de acerto.
# -m sets the max memory for items (in MB)
memcached -m 64 # default: 64 MB
memcached -m 4096 # 4 GB
# once -m is reached, memcached stops allocating new slab pages and
# relies on LRU eviction within each class.
#
# -M flips behavior: instead of evicting, return an ERROR on writes
# when memory is full (rarely what you want for a cache).
memcached -m 512 -M
# resize the memory cap at runtime (bytes):
cache_memlimit 2147483648 # 2 GB
# -> OK (only grows/shrinks the page pool; doesn't drop items
# unless shrinking forces eviction)
# monitor:
stats
# STAT bytes 424463360 # current bytes in use
# STAT limit_maxbytes 536870912 # the -m limitPolíticas e Ajuste de Despejo
A única política de despejo do Memcached é LRU por slab — não há opção LFU nem aleatória. Para reduzir despejos: aumente -m, encurte TTLs, rebalanceie tamanhos de valor ou ajuste -f. Builds modernos adicionam um LRU crawler e a capacidade de reatribuir páginas de slab (slabs reassign / slabs automove) para mitigar a calcificação. Detecte uma classe quente com os contadores evicted/outofmemory do stats items.
# memcached's only eviction policy is LRU (per slab class).
# (Redis offers LRU/LFU/random/TTL; memcached does not.)
#
# 1.6+ adds an LRU crawler + "temporary" vs "permanent" LRU tiers:
# lru_crawler enable
# lru_crawler tocrawl 1000
#
# to reduce evictions:
# - increase -m (more memory)
# - shorten TTLs so items self-expire before LRU drops them
# - rebalance value sizes (avoid one hot slab class)
# - tune -f so popular sizes map to well-populated classes
#
# detect a hot/evicting class:
stats items
# STAT items:5:evicted 9999 <- class 5 is under pressure
# STAT items:5:outofmemory 0
# rebalance slab memory automatically (1.5+):
slabs reassign 5 1 # move a page from class 5 to class 1
slabs automove 1 # let the server auto-rebalance (cautious mode)Slab Automove e Reassign
slabs reassign (manual) e slabs automove (1.5+, automático) permitem rebalancear páginas de slab de uma classe com chunks livres para uma sob pressão de despejo — a cura para a calcificação de slab. automove=1 é um movimentador cauteloso e lento em segundo plano, seguro para produção; =2 é agressivo e experimental. Sempre verifique com stats slabs antes e depois — uma reatribuição errada pode deixar uma classe faminta.
# 1.5+ lets you move a slab PAGE from a class with free chunks
# to a class under memory pressure.
#
# manual one-shot move:
slabs reassign 1 5 # take a page from class 1, give to class 5
# -> DONE (or BUSY if the page is being freed)
# automatic rebalancing (runs in the background):
slabs automove 0 # off (default)
slabs automove 1 # cautious auto-move (slow, safe)
slabs automove 2 # aggressive (experimental; watch carefully)
# the automover watches evictions/free chunks and slowly shifts
# pages to relieve pressure. It's conservative by design.
# check current slab state:
stats slabs
# STAT 1:total_pages 4
# STAT 1:free_chunks 0 <- class 1 is full
# STAT 5:total_pages 12
# STAT 5:free_chunks 8000 <- class 5 has room to giveOtimização de Desempenho
noreply e Pipelining
noreply corta a resposta por escrita, e o pipelining agrupa muitos comandos numa única ida e volta de rede — juntos, são a maior alavanca de rendimento para escritas em massa. Multi-get faz o mesmo para leituras. O custo do noreply é perder o feedback de erro por comando, então reserve-o para escritas não críticas e de alto volume, e mantenha respostas ligadas para qualquer coisa em que uma falha precise aparecer.
# noreply skips the server's response for write commands.
# use it for fire-and-forget writes to cut latency & network:
set k1 0 0 5 noreply
hello
set k2 0 0 5 noreply
world
# (no STORED echoed back)
# pipelining: send many commands in one batch without waiting for
# each response (binary protocol and most clients support this).
# ideal for bulk inserts/refreshes.
# trade-off:
# + fewer round-trips, higher throughput
# - no error feedback per command (use sparingly for critical writes)
# multi-get is the read-side equivalent: one request, N keys
get user:1 user:2 user:3 user:4Protocolo Binário
O protocolo binário é mais eficiente que o ASCII — um header fixo de 24 bytes em vez de parsing de texto, operações quiet nativas (estilo noreply) para pipelining e suporte a SASL para auth. Para valores pequenos e escritas em massa de alto rendimento, é mensuravelmente mais rápido. O servidor fala ambos os protocolos na mesma porta, então habilitá-lo é puramente uma escolha do lado do cliente. Prefira-o em clientes de produção.
# the binary protocol (vs ASCII text) is more efficient:
# - fixed 24-byte header (no string parsing)
# - supports SASL authentication
# - supports pipelining and quiet (noreply-equivalent) ops natively
# - smaller wire footprint for small values
#
# enable on the client side (the server speaks both on the same port):
# pymemcache: Client(..., allow_unicode_keys=True, default_noreply=True)
# spymemcached: use the binary connection factory
# libmemcached: MEMCACHED_BINARY_PROTOCOL
# binary quiet ops (Noop/SetQ/AddQ/...):
# pipelined writes that only reply on error — perfect for bulk loads
# the server listens for both protocols on 11211 by default;
# no server-side flag is requiredPooling de Conexões
Pooling de conexões é essencial — abrir uma conexão TCP por requisição queima portas efêmeras e adiciona latência. Mantenha um pool pequeno de conexões persistentes por servidor por processo, dimensionado à sua concorrência. Vigie total_connections vs curr_connections nas stats: se total cresce com o tráfego enquanto curr fica estável, você está com pool; se total explode, não está. A maioria dos clientes agrupa internamente quando configurado.
# opening a TCP connection per request is extremely wasteful.
# reuse connections via a pool:
#
# - keep N persistent connections per server per app process
# - checkout -> use -> checkin (don't close)
# - size the pool to your concurrency, not your request rate
#
# pymemcache: HashClient manages a pool internally
# Node.js memcached: set poolSize
# PHP: persistent connections via memcached::OPT_CONNECT_TIMEOUT
# Java spymemcached: one MemcachedClient (thread-safe, NIO)
#
# signs of a missing pool:
# - high total_connections in stats (grows with traffic)
# - TIME_WAIT exhaustion on the server (ephemeral ports)
# - request latency dominated by connect() not get()/set()
stats
# STAT total_connections 1000000 <- too high; pool your conns
# STAT curr_connections 50 <- healthy pooled countOperações em Massa (Multi-Get)
Um multi-get busca N chaves numa única ida e volta — a maior otimização de leitura disponível. Os clientes espalham as chaves pelos servidores em paralelo, então a latência é limitada pelo servidor mais lento, não pela contagem de chaves. Divida multi-gets muito grandes (ex.: 100 chaves) em lotes, para que nenhuma thread de servidor seja monopolizada, e lembre que chaves ausentes estão silenciosamente ausentes do map de resultado.
# fetching N keys in one get is far cheaper than N single gets:
# 1 network round-trip instead of N
# server parses 1 command instead of N
# text protocol: space-separated keys
get user:1 user:2 user:3 user:4 user:5
# clients wrap this:
# pymemcache: mc.get_many([...])
# Node.js: mc.getMulti([...])
# PHP: $mc->getMulti([...])
# Go: mc.GetMulti([]string{...})
# best practices:
# - chunk very large multi-gets (e.g. 100 keys at a time)
# so no single server thread is monopolized
# - keys in a multi-get fan out to multiple servers — the client
# parallelizes, so a multi-get is bound by the SLOWEST server
# - missing keys are simply absent from the resultDimensionando Valores Corretamente
Como os itens são arredondados para o próximo tamanho de chunk, o tamanho do valor dirige diretamente a fragmentação interna — um valor de 60 bytes num chunk de 96 bytes desperdiça 37%. Dimensione os valores corretamente: corte espaços do JSON, comprima qualquer coisa acima de ~1KB (e use um bit de flags para marcar), e cacheie projeções em vez de blobs inteiros. Inspecione seu histograma de tamanhos com stats sizes e ajuste -f para que os tamanhos comuns caiam perto das fronteiras de chunk.
# because of the slab allocator, value size drives memory waste:
#
# a 60-byte value -> 96-byte chunk -> 36 bytes wasted (37%!)
# a 97-byte value -> 120-byte chunk -> 23 bytes wasted (19%)
#
# right-size values to fit chunk boundaries:
# - trim/normalize JSON before caching (drop whitespace, short keys)
# - compress large values (>1KB) with gzip/snappy; set a flags bit
# - avoid caching huge blobs; cache projections instead
#
# check your size distribution:
stats sizes # (off-peak; it locks)
# pick -f so common sizes land near chunk boundaries:
# if most values are 100-200 bytes, -f 1.25 is fine
# if values cluster at a few sizes, tune -f to match
# flags bit to mark compression:
set bigval 2 0 4096 # flags=2 means "gzip compressed" (your convention)Evitando Chaves Quentes
Uma chave quente é um gargalo de servidor único e thread única — suas leituras se serializam num nó enquanto outros ficam ociosos. Fragmente-a em N buckets (leia um bucket aleatório, escreva em cada um na atualização), adicione um TTL de 1 segundo no cliente para coalescer recargas, ou mova-a para um LRU no próprio processo. Detecte chaves quentes por desequilíbrio de CPU por servidor ou, na 1.6+, lru_crawler metadump para espiar a frequência de acesso.
# a single hot key creates a bottleneck: it lives on ONE server
# and ONE worker thread, so concurrent reads serialize.
#
# symptoms: one memcached server at 100% CPU while others idle;
# one slab class churning while others are calm.
#
# fixes:
# 1) shard the hot key into N buckets:
# key = "hot:" + str(random.randint(0, 9)) # 10 buckets
# write to all N on update; read from a random one
# 2) add a short client-side TTL (e.g. 1s) to coalesce reloads
# 3) precompute and rotate (cache the rendered page, not the query)
# 4) move the hot value closer to the app (in-process LRU)
#
# detect with:
# - per-server CPU/stats imbalance
# - lru_crawler metadump all (peek at access frequency, 1.6+)Monitoramento
Estatísticas Centrais a Vigiar
As quatro métricas de manchete são: taxa de acerto (get_hits/cmd_get, alvo >95%), evictions (pressão de memória, alvo 0 em estado estável), utilização de memória (bytes/limit_maxbytes, alvo <90%) e listen_disabled_num (atingimentos do limite de conexões, alvo 0). Acompanhe-as como taxas ao longo do tempo, não só contadores. Uma taxa de acerto caindo ou evictions subindo são os sinais mais precoces de um cache insalubre.
# the four numbers to monitor continuously:
stats
# STAT cmd_get, cmd_set # throughput (ops/sec deltas)
# STAT get_hits, get_misses # hit rate = hits / cmd_get
# STAT evictions # memory pressure (rising = bad)
# STAT bytes / limit_maxbytes # memory utilization %
# derived metrics:
# hit_rate = get_hits / cmd_get # target > 95%
# eviction_r = evictions_delta / cmd_set_delta
# mem_usage = bytes / limit_maxbytes # target < 90%
# connection health:
# STAT curr_connections # active conns
# STAT listen_disabled_num # >0 = hit -c limit (refused conns)
# alert thresholds (suggestions):
# hit_rate < 90% -> investigate cold keys / undersizing
# evictions > 0 (steady)-> add memory or shorten TTLs
# listen_disabled_num > 0 -> raise -cmemcached-tool
memcached-tool é a CLI incluída para uma checagem ad hoc rápida: stats para uma tabela por slab, display para uma visão de atualização ao vivo, dump para espiar as chaves (só depuração — percorre o LRU). Perfeito para uma batida única via SSH, mas não para monitoramento contínuo; pareie com um exporter Prometheus e Grafana para dashboards e alertas de produção.
# memcached-tool ships with the server — quick CLI stats:
memcached-tool host:port stats
memcached-tool host:port display # live-refreshing table
memcached-tool host:port dump # dump keys (debug only!)
# sample output of "stats":
# # Item_Size Max_age Pages Count Full? Evicted Evict_Time
# 1 96B 3600s 1 100 no 0 0
# 2 120B 7200s 2 250 no 0 0
# ...
# great for a one-off SSH check; not for continuous monitoring.
# for the latter, use a Prometheus exporter + Grafana.Monitoramento via Telnet
Telnet ou netcat para a porta 11211 dá acesso interativo instantâneo ao protocolo de texto para checagens ad hoc: stats, stats settings, stats items, stats slabs, version. Use one-liners com nc para scripts (echo 'stats' | nc -q 1 host 11211). Lembre que flush_all é destrutivo — nunca crie um apelido casual para ele. Esta é a forma de menor atrito de inspecionar um nó.
# quick interactive check via telnet/nc:
telnet localhost 11211
stats
stats settings
stats items
stats slabs
version
quit
# or one-liners with nc:
echo "stats" | nc -q 1 localhost 11211
echo "stats slabs" | nc -q 1 localhost 11211
# flush all keys (DESTRUCTIVE — use with care):
echo "flush_all" | nc -q 1 localhost 11211
# tip: pipe commands from a file for repeatable checks
nc localhost 11211 < checks.txtExporter Prometheus e Grafana
memcached_exporter é a integração Prometheus padrão — rode um ao lado de cada nó e colete :9150. Dashboards Grafana então acompanham taxa de acerto, taxa de despejo, uso de memória e preenchimento por slab. Alerte para quedas de taxa de acerto abaixo de 90%, quaisquer despejos estáveis, memória acima de 90% e listen_disabled_num > 0. Isso dá visibilidade contínua e histórica que o telnet ad hoc não dá.
# popular exporters scrape memcached stats into Prometheus:
#
# 1) memcached_exporter (official):
# https://github.com/prometheus/memcached_exporter
# run alongside each memcached instance:
memcached_exporter --memcached.address=localhost:11211 \
--web.listen-address=:9150
# 2) scrape config in prometheus.yml:
# - job_name: 'memcached'
# static_configs:
# - targets: ['mc1:9150','mc2:9150','mc3:9150']
# 3) Grafana dashboard (e.g. community id 37 or custom):
# - hit rate (get_hits / cmd_get)
# - eviction rate (rate(evictions[5m]))
# - memory usage (bytes / limit_maxbytes)
# - connections (curr_connections, listen_disabled_num)
# - per-slab fill / evictions
# alert on: hit rate < 90%, evictions > 0 steady, mem > 90%Métricas-Chave e Alertas
Alerte para degradação da taxa de acerto (aviso <90%, crítico <75%), quaisquer despejos estáveis, memória acima de 90% e quaisquer conexões recusadas. Sempre correlacione métricas de cache com métricas da origem — uma queda de taxa de acerto pareada com um pico de CPU do banco é a assinatura de uma tempestade de cache-miss, e despejos subindo pareados com latência da origem subindo apontam para um cache pequeno demais. Acompanhe resets de uptime para capturar reinícios silenciosos.
# metric alert when severity
# ------------------------------------------------------------------
# hit_rate < 90% sustained warning
# hit_rate < 75% sustained critical
# evictions (rate) > 0 steady warning
# evictions (rate) > 100/min critical
# mem_usage > 90% warning
# mem_usage > 98% critical
# listen_disabled_num > 0 (refused conns) critical
# curr_connections > 80% of -c warning
# uptime resets (process restarted) info
# cmd_get/cmd_set rates sudden drop (app -> cache down) critical
# pair cache metrics with origin metrics:
# if cache hit rate drops AND DB CPU spikes -> cache miss storm
# if cache evictions rise AND origin latency rises -> undersizedSegurança
Isolamento de Rede
O protocolo de texto do Memcached não tem autenticação, então nunca deve ser exposto publicamente — vincule a 127.0.0.1 ou a uma NIC privada com -l, desative o UDP com -U 0 se não for usar, e firewalle a 11211 só para sub-redes do app. Um Memcached alcançável publicamente é tanto um cache de dados aberto quanto um vetor de DDoS por amplificação UDP (CVE-2018-1000115). O endereço de escuta padrão é todas as interfaces — sempre sobrescreva.
# memcached has NO authentication in the text protocol.
# it MUST NOT be exposed to the public internet.
#
# bind to loopback or a private network only:
memcached -l 127.0.0.1 # local only
memcached -l 10.0.0.5 # private NIC
memcached -l 10.0.0.5 -U 0 # also disable UDP
# firewall: deny 11211 from outside, allow only app subnets
# iptables example:
# iptables -A INPUT -p tcp --dport 11211 -s 10.0.0.0/24 -j ACCEPT
# iptables -A INPUT -p tcp --dport 11211 -j DROP
# CRITICAL: the default -l is ALL interfaces.
# A public memcached is an open cache AND a UDP amplification
# vector (CVE-2018-1000115 etc.) — disable UDP if unused.Autenticação SASL (Protocolo Binário)
Autenticação SASL está disponível só no protocolo binário (inicie o servidor com -S). Usa credenciais PLAIN durante a fase de setup da conexão, adicionando uma ida e volta que o pooling amortiza. Use SASL em redes compartilhadas ou multi-inquilino, onde o isolamento de rede sozinho é insuficiente. O protocolo de texto não consegue autenticar — se precisar de auth, use o protocolo binário de ponta a ponta.
# the BINARY protocol supports SASL (PLAIN) authentication.
# the text protocol does NOT.
#
# server: start with SASL enabled (built-in in most distros)
memcached -S -l 10.0.0.5
# create a SASL user (e.g. via saslpasswd2):
echo -n "myuser" | saslpasswd2 -p -a memcached myuser
# client: provide credentials
# pymemcache: Client(..., sasl_credentials=("myuser","pass"))
# spymemcached: use the binary factory + auth descriptor
# libmemcached: MEMCACHED_BEHAVIOR_SASL
# note: SASL adds a round-trip at connection setup; pooled
# connections amortize this. Use it on shared/multi-tenant networks
# where -l alone isn't enough.Criptografia e TLS
Memcached não tem TLS nativo — para criptografar tráfego, termine o TLS num sidecar como stunnel ou HAProxy à frente de cada nó, e rode o memcached puro atrás dele no loopback. Para a maioria das implantações em LAN, isolamento de rede mais SASL opcional basta; reserve TLS para fluxos entre redes ou ambientes que exijam conformidade. Forks mais novos (e alguns serviços gerenciados na nuvem) adicionam TLS nativo.
# memcached itself does NOT support TLS/SSL natively.
# to encrypt traffic, terminate TLS in front of the server:
#
# app --TLS--> stunnel/haproxy --plain--> memcached
#
# stunnel example (server side):
# [memcached]
# accept = 11443
# connect = 127.0.0.1:11211
# cert = /etc/stunnel/mc.pem
#
# the client also needs a stunnel/haproxy side, OR a client that
# speaks TLS (some newer forks/patches add native TLS).
#
# for most LAN deployments, network isolation + SASL is enough;
# reserve TLS for cross-network or compliance-required flows.Firewall e Controle de Acesso
Camade suas defesas: vincule a uma NIC privada, firewalle para sub-redes do app, desative o UDP, adicione SASL em redes compartilhadas, rode como usuário não root e aplique endurecimento systemd (NoNewPrivileges, ProtectSystem, PrivateTmp). Criticamente, nunca guarde segredos crus no Memcached — é um cache, não um cofre; criptografe-então-cacheie ou mantenha segredos num gerenciador de segredos dedicado e cacheie só referências não sensíveis.
# defense in depth for memcached:
#
# 1) bind to a private interface (-l 10.0.0.5)
# 2) firewall 11211 to app subnets only
# 3) disable UDP if unused (-U 0) — UDP is an amplification vector
# 4) use SASL on shared networks
# 5) TLS via stunnel for cross-network
# 6) run as a non-root user (-u memcache)
# 7) drop privileges / use systemd hardening
# 8) never store secrets in memcached unencrypted — it's a cache,
# not a vault (use a secrets manager + encrypt-then-cache)
# systemd hardening example:
# [Service]
# User=memcache
# NoNewPrivileges=true
# ProtectSystem=strict
# PrivateTmp=trueBoas Práticas de Segurança
As regras cardinais: nunca exponha o Memcached publicamente, sempre vincule a uma interface privada, desative o UDP e use SASL em redes compartilhadas. Não guarde segredos nem PII sem criptografia; namespaceie as chaves por inquilino para prevenir vazamento entre usuários. Mantenha o servidor atualizado, audite conexões com stats conns e trate uma violação de cache como violação de dados — rotacione quaisquer tokens que possam ter sido cacheados.
# 1) NEVER expose memcached to the internet (no auth in text proto)
# 2) ALWAYS set -l to loopback or a private address
# 3) disable UDP (-U 0) unless you specifically need it
# 4) use SASL on the binary protocol for multi-tenant networks
# 5) don't store secrets/PII in the cache unencrypted
# 6) namespace keys per-tenant to avoid cross-tenant leakage
# (e.g. "tnt:42:user:1" — never shared global keys)
# 7) keep memcached updated (security CVEs do happen)
# 8) audit with stats conns to see who's connected
# 9) log and alert on unexpected connection sources
# 10) treat a cache breach as a data breach: rotate any tokens that
# might have been cachedMemcached vs Redis
Tipos de Dados e Recursos
Memcached é um cache chave-valor puro de strings; Redis é um servidor de estruturas de dados com listas, hashes, sets, sorted sets, streams, scripting Lua, transações, pub/sub e módulos. A riqueza do Redis é uma força quando você precisa, mas o minimalismo do Memcached é um recurso para cache puro — menos superfície, menos para configurar errado. Escolha por se você precisa de estruturas de dados no servidor.
# Memcached:
# - strings only (key -> bytes), plus the numeric incr/decr trick
# - no lists, hashes, sets, sorted sets, streams, pub/sub
# - no server-side scripting (no Lua)
# - no transactions (single-key CAS only)
# - no keyspace notifications
#
# Redis:
# - rich types: strings, lists, hashes, sets, zsets, streams, ...
# - Lua scripting, MULTI/EXEC transactions, pub/sub
# - modules (RedisJSON, RediSearch, RedisGraph, ...)
# - per-key TTL on any type
#
# verdict: Redis is a data-structure server; memcached is a
# pure key-value cache. Pick memcached when you only need a cache.Persistência
Memcached tem zero persistência — um reinício o esvazia por design, e o cache é sempre descartável. Redis oferece snapshots RDB e durabilidade AOF mais replicação, então pode servir como datastore primário. Se você precisa que o cache sobreviva a reinícios ou guarde dados autoritativos, Redis vence; se você quer um cache puro e volátil que se reconstrói em miss, a simplicidade do Memcached é uma virtude.
# Memcached:
# - NO persistence. A restart loses everything. By design.
# - no snapshots, no AOF, no replication
# - the cache is always disposable; rebuild from the DB on miss
#
# Redis:
# - RDB snapshots (point-in-time) and AOF (append-only log)
# - can act as a primary datastore with durability
# - replication + sentinel/cluster for HA
#
# verdict: if you need the cache to survive restarts, use Redis.
# if you want a pure volatile cache (and rebuild on miss), memcached's
# lack of persistence is simpler and faster.Replicação e Clustering
Memcached não tem clustering nem replicação no servidor — a distribuição é totalmente no cliente, e um nó morto perde suas chaves permanentemente. Redis oferece replicação mestre/réplica, Sentinel para HA e Redis Cluster para sharding com failover automático. Memcached é mais simples de operar (sem gossip, sem lógica de failover), mas não oferece HA; Redis troca complexidade operacional por resiliência real.
# Memcached:
# - NO server-side clustering or replication
# - sharding is 100% client-side (consistent hashing)
# - a dead node loses its keys; clients reroute
# - scale out = add nodes to the ring
#
# Redis:
# - master/replica replication (async)
# - Sentinel for HA/failover
# - Redis Cluster for sharding + automatic failover
# - more moving parts, but true HA
#
# verdict: memcached is simpler to operate (no cluster gossip) but
# has no failover — a dead node is data loss for its keys.
# Redis gives you replication + failover at the cost of complexity.Características de Desempenho
Ambos são em memória e sub-milissegundo. Memcached é multithread por padrão e escala pelos núcleos para get/set puro, enquanto Redis é (em sua maioria) single-threaded para execução de comandos — então numa máquina multicore grande fazendo só get/set, o Memcached pode atingir QPS mais alto. Para a maioria dos apps reais a diferença é insignificante; escolha por recursos e encaixe operacional, não por microbenchmarks.
# Both are in-memory and very fast (sub-millisecond, >100k ops/s).
#
# Memcached:
# - multi-threaded by default (-t workers); scales across cores
# - simple protocol, low overhead per op
# - excellent for high-throughput pure get/set
#
# Redis:
# - single-threaded command execution (Redis 6+ threads the I/O)
# - one core does the work; more cores don't speed a single command
# - richer ops can be slower, but core get/set is comparable
#
# verdict: for pure get/set at very high QPS on a big multi-core box,
# memcached's multi-threading can win. For most apps the difference
# is negligible; pick by features, not microbenchmarks.Eficiência de Memória
O alocador de slabs do Memcached é enxuto para blobs opacos, mas desperdiça espaço no arredondamento de chunks; Redis tem custo por chave/campo, mas escolhe codificações compactas (listpack) para estruturas pequenas. Nenhum é universalmente menor — Memcached vence para blobs uniformes, Redis pode vencer para dados estruturados pequenos. Sempre meça com as suas próprias formas de valor antes de presumir que um é mais barato.
# Memcached:
# - slab allocator: fixed chunks, some internal fragmentation
# - no per-field overhead (it's just bytes)
# - very lean for small uniform values
# - can waste memory if value sizes don't fit slab classes
#
# Redis:
# - per-key/per-field overhead (complex internal structures)
# - many encodings (listpack, hashtable, skiplist, ...) chosen by size
# - richer structures use more memory than a flat string
# - but more memory-efficient for small structured data via listpack
#
# verdict: memcached is leaner for opaque blobs; Redis can be leaner
# for small structured data (listpack). Measure with your own data.Quando Escolher Cada Um
Escolha Memcached para um cache get/set puro e descartável, onde simplicidade operacional e escala multithread importam. Escolha Redis quando precisar de estruturas de dados, persistência, replicação, clustering, Lua, pub/sub ou módulos. Não são mutuamente exclusivos — muitas pilhas rodam ambos, usando Memcached para cache cru de páginas/consultas e Redis para sessões, leaderboards, limitação de taxa e streams.
# Choose Memcached when:
# - you need a pure, disposable get/set cache
# - you value operational simplicity (no clustering, no persistence)
# - you want multi-threaded scaling on a big box
# - your data is opaque blobs and you rebuild on miss
#
# Choose Redis when:
# - you need data structures (lists, hashes, sets, zsets, streams)
# - you need persistence or durability
# - you need replication / failover / clustering
# - you need server-side logic (Lua, pub/sub, modules)
# - you need per-key TTL on rich types
#
# both can coexist: memcached for raw page/query cache, Redis for
# sessions, leaderboards, rate-limiting, streams.Solução de Problemas
Conexão Recusada
Conexão recusada geralmente significa que o servidor não está rodando, não está escutando no endereço esperado (um -l vinculado ao loopback bloqueia clientes remotos), está atrás de firewall ou atingiu o limite de conexões -c (listen_disabled_num > 0). Percorra a checklist: ps/systemctl para o processo, ss/netstat para o listener, iptables para o firewall, stats para o limite de conexões e journalctl para logs de crash.
# symptom: client reports "connection refused" to 11211
#
# 1) is memcached running?
ps aux | grep memcached
systemctl status memcached
# 2) is it listening on the expected address/port?
ss -tlnp | grep 11211
netstat -tlnp | grep 11211
# 3) check the -l bind address (default = ALL; you may have set 127.0.0.1)
# a client on another host can't reach a loopback-bound server
# 4) firewall blocking?
iptables -L -n | grep 11211
# 5) hit the -c connection limit? (check listen_disabled_num)
echo "stats" | nc -q 1 host 11211 | grep listen_disabled
# 6) check memcached logs / journalctl
journalctl -u memcached -n 100Tempestades de Despejo
Despejos subindo com o cache cheio significam que seu working set excede -m. Diagnostique com stats (bytes == limit_maxbytes) e stats items (qual classe de slab está despejando). Correções: aumente -m, encurte TTLs para que itens expirem sozinhos, rebalanceie páginas de slab com slabs reassign/automove, e cace um escritor descontrolado inflando valores. Um cache persistentemente cheio precisa de mais memória ou de um working set menor.
# symptom: evictions counter rising fast, hit rate dropping
#
# diagnosis:
stats
# STAT evictions 999999 <- climbing
# STAT bytes 67108864
# STAT limit_maxbytes 67108864 <- 100% full
stats items
# STAT items:3:evicted 500000 <- slab class 3 is the victim
# STAT items:3:outofmemory 0
# fixes:
# 1) add memory: raise -m (or cache_memlimit at runtime)
# 2) shorten TTLs so items self-expire before LRU drops them
# 3) rebalance slab classes: slabs reassign <donor> <receiver>
# or: slabs automove 1
# 4) check for a runaway writer creating oversized values
# 5) review your working set — maybe you're caching too muchBaixa Taxa de Acerto
Uma taxa de acerto baixa (<90%) com alta carga no banco geralmente significa que os TTLs são curtos demais, o working set excede a memória (despejos), as chaves não estão sendo reutilizadas (componentes voláteis como timestamps na chave), é um começo frio, ou os clientes divergem na config ketama e as chaves caem em servidores diferentes. Verifique que cada um dos clientes compartilha listas de servidores e hashing idênticos, e confira os logs do app por padrões de reuso de chaves.
# symptom: hit rate < 90%, DB load high
#
# diagnosis:
stats
# STAT cmd_get 100000
# STAT get_hits 70000 <- 70% hit rate, too low
# STAT get_misses 30000
# common causes:
# 1) TTL too short -> items expire before reuse (raise TTL)
# 2) working set > cache memory -> evictions (see eviction storm)
# 3) keys not reused -> each request computes a unique key
# (e.g. including a timestamp; remove volatile components)
# 4) cold start -> warmup period; preheat the cache
# 5) multiple client configs -> keys hashed to different servers
# (verify all clients use the same ketama config)
# 6) cache invalidated too eagerly on writes (delete too broad)
# check TTL distribution vs access patterns in your app logsCalcificação de Slab
Calcificação de slab é quando a memória fica presa em classes que não precisam dela enquanto outra classe passa por despejos — as páginas não migram sozinhas. Diagnostique com stats slabs (free_chunks vs total_pages) e stats items (despejados por classe). Corrija com slabs reassign (único disparo) ou slabs automove 1 (segundo plano), e previna recorrência ajustando -f para casar com sua distribuição de tamanhos de valor.
# symptom: one slab class keeps evicting while another has free chunks
#
# diagnosis:
stats slabs
# STAT 1:total_pages 4 STAT 1:free_chunks 0 <- class 1 full
# STAT 5:total_pages 12 STAT 5:free_chunks 8000 <- class 5 idle
#
# stats items
# STAT items:1:evicted 99999 <- class 1 churning
# cause: over time, all pages got assigned to popular classes;
# memory is stuck and can't move to where it's needed.
# fixes:
# 1) one-shot: slabs reassign 5 1 # move a page class5 -> class1
# 2) auto: slabs automove 1 # cautious background rebalance
# 3) restart with a better -f growth factor that matches your data
# 4) enable lru_crawler for smarter eviction
# verify after:
stats slabsAlto Uso de Memória
Uso de memória inesperado costuma ser fragmentação interna (valores que não cabem nos chunks), valores inflados (JSON não comprimido) ou pura contagem de chaves (custo por item). Diagnostique com stats (bytes vs limit_maxbytes) e stats slabs (chunks usados vs totais). Correções: comprima valores grandes, corte espaços e nomes de chaves, ajuste -f para reduzir desperdício e verifique que -m casa com o working set de que você realmente precisa.
# symptom: memcached using more memory than expected
#
# diagnosis:
stats
# STAT bytes 600000000 # actual item bytes
# STAT limit_maxbytes 671088640 # the -m cap
# STAT bytes_read / bytes_written help gauge traffic
stats slabs
# look at used_chunks vs total_chunks per class — internal
# fragmentation = (total_chunks * chunk_size) - bytes
# common causes:
# 1) internal fragmentation (values don't fit chunks well)
# 2) bloated values (cache full JSON with whitespace; compress!)
# 3) too many keys (key+metadata overhead per item)
# 4) memory leak in the client holding dead connections
# 5) -m is just set high and the working set filled it
# fix: compress large values, trim keys, tune -f, lower -mRespostas Lentas e Timeouts
Respostas lentas costumam vir de uma chave quente se serializando numa thread, um multi-get grande demais bloqueando o servidor, valores enormes saturando a rede, latência de rede app-para-cache, saturação de CPU por threads -t insuficientes ou — criticamente — o Memcached trocando para disco (nunca deixe trocar; fixe -m abaixo da RAM física). Defina timeouts agressivos no cliente (50-100ms) para que um cache lento degrade para a origem em vez de prender as requisições.
# symptom: get/set taking >10ms or timing out
#
# 1) a hot key serializing on one server thread (see hot keys)
# 2) huge multi-get blocking a server thread — chunk it
# 3) oversized values (multi-MB) saturating the network/parse
# 4) network latency between app and cache (co-locate them!)
# 5) server CPU saturated (-t too low for load)
# 6) swap! memcached must NEVER swap — check free -m; pin -m below RAM
#
# diagnose:
stats
# STAT curr_connections 4000 <- near -c? pool leak?
# STAT threads 4 <- raise -t?
# top -H -p <pid> <- which thread is hot?
# on the client: set aggressive timeouts (e.g. 50-100ms) so a slow
# cache degrades gracefully to the origin instead of stallingConfiguração de Implantação
Rodando como Daemon
Rode o Memcached como daemon com -d, sempre abandonando privilégios com -u para um usuário não root. As flags de produção essenciais são -m (memória), -l (endereço de vinculação — nunca deixe em todas as interfaces), -c (limite de conexões), -t (threads) e -f (fator de crescimento de slabs). Escreva um pidfile com -P para gestão fácil, e verifique o processo com uma checagem rápida de versão via netcat.
# start memcached as a background daemon (-d):
memcached -d -m 256 -p 11211 -u memcache -l 127.0.0.1 -c 2048
# common production flags:
# -d daemonize
# -u memcache drop privileges to this user
# -m 256 256 MB item memory
# -l 127.0.0.1 bind to loopback (or private NIC)
# -c 2048 max connections
# -t 8 8 worker threads
# -f 1.25 slab growth factor
# -I 1m max item size
# -v / -vv log verbosity
# -P /var/run/memcached.pid write a pidfile
# check it's up:
echo "version" | nc -q 1 127.0.0.1 11211
# -> VERSION 1.6.24Serviço Systemd
Uma unidade systemd dá reinício automático (Restart=on-failure), abandono de privilégios (User=memcache), limites de descritores de arquivo (LimitNOFILE para muitas conexões) e endurecimento de segurança (NoNewPrivileges, ProtectSystem, PrivateTmp). A maioria das distros traz uma unidade padrão que você pode sobrescrever via /etc/systemd/system/memcached.service.d/override.conf, em vez de reescrever o arquivo inteiro — prefira isso por portabilidade.
# /etc/systemd/system/memcached.service
[Unit]
Description=Memcached
After=network.target
[Service]
Type=simple
User=memcache
Group=memcache
ExecStart=/usr/bin/memcached -m 256 -p 11211 -l 127.0.0.1 -c 2048 -t 8 -f 1.25
Restart=on-failure
RestartSec=2
LimitNOFILE=8192
# hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/var/run
[Install]
WantedBy=multi-user.target
# enable and start:
# systemctl daemon-reload
# systemctl enable --now memcached
# systemctl status memcachedImplantação com Docker
No Docker, lembre que há dois limites de memória: o -m do memcached (memória de itens) e o teto de memória do contêiner (docker -m). Sempre defina o teto do contêiner acima do -m do memcached para deixar espaço ao runtime e às conexões, senão o OOM killer ataca. Fixe uma tag de versão específica (memcached:1.6) em vez de :latest, por reprodutibilidade, e restart=unless-stopped por resiliência.
# run memcached in Docker:
docker run -d \
--name memcached \
-p 11211:11211 \
-m 512m \
--restart=unless-stopped \
memcached:1.6 \
-m 256 -c 2048 -t 4 -f 1.25
# note: -m inside the container is memcached's item memory (256 MB);
# the docker -m 512m limit caps the whole container (memcached +
# overhead). Always set the docker limit HIGHER than memcached's -m.
# docker-compose snippet:
# memcached:
# image: memcached:1.6
# command: -m 256 -c 2048 -t 4
# ports:
# - "11211:11211"
# restart: unless-stoppedMúltiplas Instâncias
Rodar múltiplas instâncias Memcached por host permite isolar classes de slab quentes, encolher o impacto de reinício por processo e usar mais núcleos — o cliente simplesmente as vê como membros adicionais do anel. O custo é mais conexões e custo de páginas de slab por processo. Para a maioria das cargas, um único processo multithread (-t para a sua contagem de núcleos) é mais simples e suficiente; divida só quando atingir um gargalo específico.
# run several memcached instances per host for isolation or to
# use more cores efficiently:
#
# instance A: port 11211, 4 GB
memcached -d -m 4096 -p 11211 -l 127.0.0.1 -t 4
# instance B: port 11212, 4 GB
memcached -d -m 4096 -p 11212 -l 127.0.0.1 -t 4
# the client treats them as two ring members (more shards).
# trade-offs:
# + isolates a hot slab class to its own process
# + smaller per-process working set = simpler restarts
# - more connections to manage
# - more memory overhead per process (slab pages don't share)
# alternative: one process with -t 8 threads (simpler, usually fine)Dimensionamento de Memória
Dimensione -m ao seu working set medido mais folga, mirando 70-80% de utilização no pico, para que tenha espaço para picos e não entre em churn de despejos. Nunca deixe o Memcached trocar para disco — mantenha -m abaixo da RAM disponível depois de contabilizar o SO e os outros processos. Se a utilização estável exceder 90%, ou aumente -m ou encolha o working set (TTLs mais curtos, menos coisas cacheadas).
# how big should -m be?
#
# 1) measure your working set: the keys actually hot in a typical hour
# 2) add headroom: target ~70-80% memory utilization at peak
# 3) leave RAM for the OS, connections, and slab overhead
#
# rule of thumb:
# -m = working_set_bytes / 0.75
#
# example: 3 GB working set -> -m 4096 (4 GB) for 75% utilization
#
# never let memcached swap:
# -m must be BELOW available RAM (check free -m)
# account for other processes on the same host
#
# monitor utilization:
stats
# STAT bytes 3221225472 # 3 GB used
# STAT limit_maxbytes 4294967296 # 4 GB cap -> 75% utilization
# if utilization > 90% steady: raise -m or shrink the working setLogs e Verbosidade
Memcached é silencioso por design; aumente a verbosidade com -v/-vv/-vvv ou o comando runtime verbosity só para depuração, já que registrar cada comando esmaga o rendimento. Em produção, rode silencioso e confie nas stats e num exporter Prometheus para visibilidade. Os logs vão para journald sob systemd ou docker logs em contêineres. Use -vv brevemente para rastrear um problema específico, depois reduza de novo.
# memcached is deliberately quiet; increase verbosity for debugging:
memcached -v # log errors + warnings
memcached -vv # also log each command (very noisy!)
memcached -vvv # even more (connection-level detail)
# change at runtime without restart:
verbosity 2 # telnet in and raise the level
verbosity 0 # back to quiet
# with systemd, logs go to journald:
journalctl -u memcached -f
# with Docker:
docker logs -f memcached
# in production, run quiet (no -v) — verbose modes are only for
# debugging, as logging every command kills throughput.
# for access patterns, use stats + an exporter instead of -vv.Tópicos Avançados
Imersão no Protocolo Binário
O header fixo de 24 bytes do protocolo binário habilita parsing eficiente, auth SASL e opcodes quiet (supressão de resposta) que tornam as operações em massa com pipeline muito mais eficientes que o protocolo de texto. Um Noop no fim de um pipeline quiet o descarrega e revela erros. A maioria dos clientes de produção assume ou prefere o protocolo binário, pelo menor custo por operação e conjunto de recursos mais rico.
# the binary protocol uses a fixed 24-byte request header:
#
# Magic (1) 0x80 request / 0x81 response
# Opcode (1) 0x01 Get / 0x02 Set / 0x03 Add / ... / 0x05 Delete ...
# Key length (2)
# Extras length (1)
# Data type (1) usually 0
# VBucket/reserved (2)
# Total body length (4) extras + key + value
# Opaque (4) client-supplied, echoed back
# CAS (8)
#
# followed by: extras | key | value
#
# "quiet" opcodes (GetQ, SetQ, ...) skip responses except on error,
# enabling efficient pipelined bulk operations.
#
# a Noop at the end flushes the pipeline and confirms success.
# prefer the binary protocol in production clients for lower overhead.Suporte a UDP
Memcached suporta UDP para buscas de alto rendimento, sem conexão e dispara-e-esquece — útil em setups especializados onde o custo do handshake TCP domina. É com perdas e limitado em tamanho, então use só para leituras de cache idempotentes. Crucialmente, UDP é um vetor conhecido de DDoS por amplificação (CVE-2018-1000115); desative-o com -U 0 em produção, a menos que tenha uma necessidade específica e com firewall.
# memcached can serve UDP (-U port, default 11211; -U 0 disables).
# UDP is for very high-throughput, fire-and-forget scenarios where
# a connection setup is too costly.
#
# each UDP datagram carries:
# frame header (8 bytes): request ID, sequence, total datagrams
# then the (possibly multi-datagram) command
#
# limits:
# - responses may arrive out of order or be lost
# - datagram size limits (~1400 bytes payload to avoid fragmentation)
# - no guarantees — use only for cacheable, idempotent lookups
#
# SECURITY: UDP is a known amplification vector (CVE-2018-1000115).
# DISABLE it (-U 0) unless you have a specific, firewalled use case.
memcached -U 0 # recommended in productionObjetos Grandes e Chunking
Embora você possa aumentar o limite de 1MB por item com -I, itens grandes prejudicam o rendimento e o equilíbrio de slabs. Um padrão melhor é o chunking no nível da aplicação: divida o valor em pedaços de ~512KB sob chaves numeradas, guarde uma chave de contagem e remonte na leitura. Isso mantém os itens amigáveis às slabs, evita monopolizar threads do servidor e torna uma falha parcial recuperável em vez de perder o blob inteiro.
# memcached's default max item size is 1 MB (-I).
# raising it (-I 4m) works but large items hurt: they're slow to
# transfer, monopolize server threads, and risk slab fragmentation.
#
# better: chunk large values yourself:
#
def set_large(key, value, ttl=3600):
chunks = [value[i:i+512*1024] for i in range(0, len(value), 512*1024)]
for idx, c in enumerate(chunks):
mc.set(key + ":" + str(idx), c, ttl)
mc.set(key + ":n", len(chunks), ttl)
def get_large(key):
n = mc.get(key + ":n")
if n is None: return None
return b"".join(mc.get(key + ":" + str(i)) for i in range(n))
# trade-off: more keys/round-trips, but smaller items fit slabs
# better and a single chunk failure doesn't lose the whole value.Namespacing e Versionamento
Memcached não tem namespaces reais — simule-os com prefixos de chave, e use um prefixo versionado para invalidar um namespace lógico inteiro de uma vez (incremente uma chave nsver para que as chaves velhas fiquem inalcançáveis e envelheçam via TTL). Incluir um prefixo de versão do app dá a cada deploy um cache fresco. Esta é a forma canônica de invalidar em massa, já que o Memcached não pode enumerar nem deletar chaves por padrão.
# memcached has no native namespaces — fake them with key prefixes.
#
# per-tenant isolation:
key = "tnt:" + tenant_id + ":user:" + user_id
# version the whole namespace to invalidate en masse:
ns_version = mc.get("nsver:user") or "1"
key = "user:" + ns_version + ":" + user_id
# to invalidate ALL user:* keys: incr "nsver:user" -> new version
# old keys become unreachable and expire via TTL
# or include a deploy version so each deploy starts fresh:
key = "v" + APP_VERSION + ":user:" + user_id
# time-bucketed namespaces for reports:
key = "report:" + today_date() # auto-expires by date
# NEVER try "flush_all user:*" — memcached can't enumerate keys.
# versioned prefixes are the canonical bulk-invalidation trick.Prevenção de Avalanche de Cache
Uma avalanche acontece quando muitas requisições erram a mesma chave expirando e todas a recomputam, martelando a origem. A correção canônica é um lock baseado em add, para que só um cliente reconstrua enquanto os outros brevemente esperam e repetem. Combine com jitter de TTL para prevenir expirações sincronizadas, e renovação proativa (renovar antes de expirar, servir velho enquanto um cliente reconstrói) para chaves quentes em que até um único miss é caro.
# a stampede: many requests miss the same expiring key, all
# recompute the same expensive value, overwhelming the origin.
#
# fix 1: lock-and-recompute (only ONE client rebuilds)
def get_with_lock(key, rebuild_fn, ttl=3600, lock_ttl=30):
val = mc.get(key)
if val is not None:
return val
# try to take a rebuild lock
if mc.add("lock:" + key, "1", ttl=lock_ttl):
try:
val = rebuild_fn() # only the winner recomputes
mc.set(key, val, ttl)
return val
finally:
mc.delete("lock:" + key)
else:
# another client is rebuilding; wait briefly and retry
time.sleep(0.05)
return get_with_lock(key, rebuild_fn, ttl, lock_ttl)
# fix 2: add jitter to TTLs so expirations don't synchronize
ttl = base_ttl + random.randint(-60, 60)
# fix 3: "dogpile" — serve a stale value while one client rebuilds
# (store value + a "refresh_at" timestamp; refresh proactively)Snippets de Memcached relacionados
Copy-paste ready code for common tasks.
set / get — Key-Value Básico
Armazenar e recuperar valores por chave com expiração e flags.
add / replace / append / prepend
Escritas condicionais e concatenação de string in-place.
cas / gets — Compare-And-Swap
Locking otimista: atualizar uma chave apenas se não mudou desde a leitura.
stats — Métricas do Servidor & Slabs
Inspecionar memória, hit rate, evictions e alocação por slab.
flush_all — Invalidar Tudo
Invalidar logicamente todas as chaves instantaneamente (lazy deletion).
Expiração, Eviction & Estratégia de TTL
Escolher TTLs sabiamente e entender como Memcached evicta sob pressão.
Protocolo Texto vs Binário & Consistent Hashing
Escolher o protocolo certo e shardar entre servidores sem reshuffling.
Padrões: Read-Through, Write-Behind & Session Cache
Aplicar Memcached a problemas comuns de cache de aplicação.
Was this helpful?