Perfilado de memoria en Go para picos de tráfico: guía de pprof

Qué hacen los picos de tráfico repentinos a la memoria de un servicio Go

Un “pico de memoria” en producción rara vez significa que un solo número subió simplemente. Puedes ver cómo el RSS (memoria del proceso) sube rápido mientras el heap de Go casi no se mueve, o el heap crece y baja en olas agudas cuando el GC se ejecuta. Al mismo tiempo, la latencia suele empeorar porque el runtime dedica más tiempo a limpiar.

Patrones comunes en las métricas:

• El RSS sube más rápido de lo esperado y a veces no baja completamente tras el pico
• El heap en uso sube y luego cae en ciclos agudos conforme el GC corre más a menudo
• La tasa de asignación salta (bytes asignados por segundo)
• El tiempo de pausa del GC y la CPU usada por GC aumentan, aunque cada pausa sea pequeña
• La latencia de las peticiones sube y la latencia tail se vuelve ruidosa

Los picos de tráfico magnifican las asignaciones por petición porque el “desperdicio” pequeño escala linealmente con la carga. Si una petición asigna 50 KB extra (buffers JSON temporales, objetos por fila al escanear, datos de contexto en middleware), a 2.000 peticiones por segundo le estás dando al asignador unos 100 MB por segundo. Go puede manejar mucho, pero el GC aún tiene que trazar y liberar esos objetos de vida corta. Cuando la asignación supera a la limpieza, el objetivo del heap crece, el RSS lo sigue y puedes alcanzar límites de memoria.

Los síntomas son familiares: kills por OOM del orquestador, saltos de latencia repentinos, más tiempo dedicado al GC y un servicio que parece “ocupado” aunque la CPU no esté saturada. También puedes sufrir thrash del GC: el servicio sigue en pie pero asigna y recoge constantemente, de modo que el throughput cae justo cuando más lo necesitas.

pprof ayuda a responder una pregunta rápido: ¿qué rutas de código asignan más y son necesarias esas asignaciones? Un perfil de heap muestra lo que está retenido ahora. Las vistas centradas en asignaciones (como alloc_space) muestran qué se crea y se desecha.

Lo que pprof no hará es explicar cada byte del RSS. RSS incluye más que el heap de Go (pilas, metadatos del runtime, mapeos del SO, asignaciones de cgo, fragmentación). pprof es mejor para señalar puntos calientes de asignación en tu código Go, no para probar un total exacto de memoria a nivel de contenedor.

Configura pprof de forma segura (paso a paso)

pprof es más fácil de usar como endpoints HTTP, pero esos endpoints pueden revelar mucho de tu servicio. Trátalos como una funcionalidad de administración, no como una API pública.

1) Añade endpoints de pprof

En Go, la configuración más simple es ejecutar pprof en un servidor administrativo separado. Eso mantiene las rutas de profiling fuera de tu router principal y del middleware.

package main

import (
	"log"
	"net/http"
	_ "net/http/pprof"
)

func main() {
	go func() {
		// Admin only: bind to localhost
		log.Println(http.ListenAndServe("127.0.0.1:6060", nil))
	}()

	// Your main server starts here...
	// http.ListenAndServe(":8080", appHandler)
	select {}
}

Si no puedes abrir un segundo puerto, puedes montar las rutas de pprof en tu servidor principal, pero es más fácil exponerlas por accidente. Un puerto administrativo separado es la opción segura por defecto.

2) Restringe el acceso antes de desplegar

Empieza con controles que sean difíciles de romper. Ligar a localhost significa que los endpoints no son accesibles desde Internet a menos que alguien también exponga ese puerto.

Una lista de comprobación rápida:

• Ejecuta pprof en un puerto de administración, no en el puerto principal orientado a usuarios
• Lía a 127.0.0.1 (o a una interfaz privada) en producción
• Añade una allowlist en el borde de red (VPN, bastion o subred interna)
• Requiere autenticación si tu borde puede hacerlo (basic auth o token)
• Verifica que puedas obtener los perfiles que realmente usarás: heap, allocs, goroutine

3) Compila y despliega con cuidado

Mantén el cambio pequeño: añade pprof, envíalo y confirma que solo es accesible desde donde esperas. Si tienes staging, pruébalo allí primero simulando algo de carga y capturando un heap y un perfil de allocs.

En producción, despliega gradualmente (una instancia o una porción pequeña del tráfico). Si pprof está mal configurado, el radio del problema se mantiene pequeño mientras lo arreglas.

Captura los perfiles adecuados durante un pico

Durante un pico, una sola instantánea rara vez es suficiente. Captura una pequeña línea de tiempo: unos minutos antes del pico (baseline), durante el pico (impacto) y unos minutos después (recuperación). Eso facilita separar cambios reales de asignación del comportamiento normal de warm-up.

Si puedes reproducir el pico con carga controlada, iguala la producción lo más posible: mezcla de peticiones, tamaños de payload y concurrencia. Un pico de peticiones pequeñas se comporta de forma muy distinta a un pico de respuestas JSON grandes.

Toma tanto un perfil de heap como un perfil centrado en asignaciones. Responden a preguntas distintas:

• Heap (inuse) muestra lo que está vivo y reteniendo memoria ahora mismo
• Asignaciones (alloc_space o alloc_objects) muestran qué se está asignando con fuerza, aunque se libere rápidamente

Un patrón práctico de captura: toma un perfil de heap, luego uno de asignaciones, y repite 30 a 60 segundos después. Dos puntos durante el pico te ayudan a ver si una ruta sospechosa es estable o está acelerando.

# examples: adjust host/port and timing to your setup
curl -o heap_during.pprof "http://127.0.0.1:6060/debug/pprof/heap"
curl -o allocs_30s.pprof "http://127.0.0.1:6060/debug/pprof/allocs?seconds=30"

Junto a los archivos pprof, registra algunas estadísticas del runtime para que puedas explicar qué hacía el GC al mismo tiempo. Tamaño del heap, número de GCs y tiempo de pausa suelen ser suficientes. Incluso una línea de log corta en cada momento de captura ayuda a correlacionar “las asignaciones subieron” con “el GC empezó a correr constantemente”.

Mantén notas del incidente mientras avanzas: versión de compilación (commit/tag), versión de Go, flags importantes, cambios de configuración y qué tráfico estaba ocurriendo (endpoints, tenants, tamaños de payload). Esos detalles suelen importar más tarde cuando comparas perfiles y descubres que la mezcla de peticiones cambió.

Cómo leer perfiles de heap y de asignaciones

Un perfil de heap responde preguntas distintas según la vista.

Inuse space muestra lo que todavía está en memoria en el momento de la captura. Úsalo para leaks, caches de larga vida o peticiones que dejan objetos atrás.

Alloc space (asignaciones totales) muestra lo que se asignó a lo largo del tiempo, aunque después se haya liberado rápidamente. Úsalo cuando los picos provocan mucho trabajo del GC, saltos de latencia o OOMs por churn.

El muestreo importa. Go no registra cada asignación. Muestrea asignaciones (controlado por runtime.MemProfileRate), así que asignaciones pequeñas y frecuentes pueden estar subrepresentadas y los números son estimaciones. Los mayores culpables suelen destacar, especialmente en condiciones de pico. Busca tendencias y los principales contribuyentes, no contabilidad perfecta.

Las vistas más útiles de pprof:

• top: lectura rápida de quién domina inuse o alloc (revisa plano y acumulado)
• list : fuentes de asignación a nivel de línea dentro de una función caliente
• graph: rutas de llamada que explican cómo se llegó allí

Los diffs son donde se vuelve práctico. Compara un perfil baseline (tráfico normal) con un perfil de pico para resaltar lo que cambió, en lugar de perseguir ruido de fondo.

Valida hallazgos con un cambio pequeño antes de un refactor grande:

• Reutiliza un buffer (o añade un pequeño sync.Pool) en el camino caliente
• Reduce la creación de objetos por petición (por ejemplo, evita construir maps intermedios para JSON)
• Vuelve a perfilar con la misma carga y confirma que el diff disminuye donde esperabas

Si los números se mueven en la dirección correcta, has encontrado una causa real, no solo un informe alarmante.

Encontrar puntos calientes de asignación en JSON

Durante picos, el trabajo con JSON puede convertirse en una factura importante de memoria porque se ejecuta en cada petición. Los puntos calientes de JSON suelen aparecer como muchas asignaciones pequeñas que fuerzan más el GC.

Señales de alarma en pprof

Si la vista de heap o de asignaciones apunta a encoding/json, examina de cerca qué le pasas. Estos patrones comúnmente inflan las asignaciones:

• Usar map[string]any (o []any) para respuestas en lugar de structs tipados
• Marshalizar el mismo objeto varias veces (por ejemplo, para logging y para devolverlo)
• Pretty printing con json.MarshalIndent en producción
• Construir JSON mediante strings temporales (fmt.Sprintf, concatenación) antes de serializar
• Convertir grandes []byte a string (o al revés) solo para cumplir una API

json.Marshal siempre asigna un nuevo []byte con toda la salida. json.NewEncoder(w).Encode(v) suele evitar ese gran buffer porque escribe a un io.Writer, pero aún puede asignar internamente, especialmente si v está lleno de any, maps o estructuras con muchos punteros.

Arreglos rápidos y experimentos simples

Empieza con structs tipados para la forma de tu respuesta. Reducen el trabajo de reflexión y evitan el boxing de interfaces por campo.

Luego elimina temporales evitables por petición: reutiliza bytes.Buffer mediante un sync.Pool (con precaución), no indentes en producción y no vuelvas a serializar solo para logs.

Pequeños experimentos que confirman que JSON es el culpable:

• Reemplaza map[string]any por un struct en un endpoint caliente y compara perfiles
• Cambia de Marshal a Encoder que escribe directamente en la respuesta
• Quita MarshalIndent o formateo de depuración y vuelve a perfilar con la misma carga
• Omite la codificación JSON para respuestas cacheadas sin cambios y mide la caída

Encontrar puntos calientes en el escaneo de consultas

Cuando la memoria salta durante un pico, las lecturas de base de datos son una sorpresa común. Es fácil enfocarse en el tiempo SQL, pero el paso de Scan puede asignar mucho por fila, especialmente cuando escaneas en tipos flexibles.

Ofensores comunes:

• Escanear en interface{} (o map[string]any) y dejar que el driver decida los tipos
• Convertir []byte a string para cada campo
• Usar wrappers nulos (sql.NullString, sql.NullInt64) en grandes conjuntos de resultados
• Traer columnas grandes de texto/blob que no necesitas siempre

Un patrón que quema memoria silenciosamente es escanear datos de fila en variables temporales y luego copiarlos a un struct real (o construir un map por fila). Si puedes escanear directamente en un struct con campos concretos, evitas asignaciones extra y comprobaciones de tipo.

El tamaño de lote y la paginación cambian tu forma de memoria. Traer 10.000 filas en un slice asigna para el crecimiento del slice y cada fila, todo de golpe. Si el handler solo necesita una página, empuja eso a la consulta y mantén el tamaño de página estable. Si debes procesar muchas filas, streamea y agrega resúmenes pequeños en vez de almacenar cada fila.

Las columnas de texto grandes necesitan cuidado. Muchos drivers devuelven texto como []byte. Convertir eso a string copia los datos, así que hacerlo por cada fila puede explotar las asignaciones. Si solo necesitas el valor a veces, retrasa la conversión o escanea menos columnas para ese endpoint.

Para confirmar si el driver o tu código está haciendo la mayor parte de las asignaciones, revisa qué domina tus perfiles:

• Si los frames apuntan a tu código de mapeo, enfócate en los targets de Scan y las conversiones
• Si los frames apuntan a database/sql o al driver, reduce filas y columnas primero y luego considera opciones específicas del driver
• Revisa tanto alloc_space como alloc_objects; muchas asignaciones pequeñas pueden ser peores que unas pocas grandes

Ejemplo: un endpoint “listar órdenes” hace SELECT * en []map[string]any. Durante un pico, cada petición construye miles de maps y strings pequeñas. Cambiar la consulta para seleccionar solo las columnas necesarias y escanear en []Order{ID int64, Status string, TotalCents int64} suele reducir las asignaciones de inmediato. La misma idea aplica si estás perfilando un backend Go generado por AppMaster: el punto caliente suele estar en cómo estructuras y escaneas los datos, no en la base de datos en sí.

Patrones de middleware que asignan por petición sin que lo notes

El middleware se siente barato porque es “solo un wrapper”, pero se ejecuta en cada petición. Durante un pico, pequeñas asignaciones por petición suman rápido y aparecen como una tasa de asignación creciente.

El middleware de logging es una fuente común: formatear strings, construir maps de campos o copiar headers para un output agradable. Los helpers de request ID pueden asignar al generar un ID, convertirlo a string y luego adjuntarlo al contexto. Incluso context.WithValue puede asignar si guardas nuevos objetos (o nuevas strings) en cada petición.

La compresión y el manejo del body son otro culpable frecuente. Si el middleware lee todo el body para “echar un vistazo” o validarlo, puedes acabar con un buffer grande por petición. El middleware de gzip puede asignar mucho si crea nuevos readers y writers cada vez en lugar de reutilizar buffers.

Capas de auth y sesión son similares. Si cada petición parsea tokens, decodifica cookies en base64 o carga blobs de sesión en structs nuevos, obtienes churn constante incluso cuando el trabajo del handler es ligero.

Tracing y métricas pueden asignar más de lo esperado cuando las labels se construyen dinámicamente. Concatenar nombres de rutas, user agents o IDs de tenant en nuevas strings por petición es un coste oculto clásico.

Patrones que suelen aparecer como “muerte por mil cortes”:

• Construir líneas de log con fmt.Sprintf y nuevos map[string]any por petición
• Copiar headers en maps o slices nuevos para logging o firma
• Asignar nuevos buffers y readers/writers de gzip en vez de hacer pooling
• Crear labels de métricas de alta cardinalidad (muchas strings únicas)
• Almacenar nuevos structs en context en cada petición

Para aislar el coste del middleware, compara dos perfiles: uno con la cadena completa habilitada y otro con el middleware temporalmente deshabilitado o reemplazado por un no-op. Una prueba simple es un endpoint de health que debería ser casi sin asignaciones. Si /health asigna mucho durante un pico, el handler no es el problema.

Si generas backends Go con AppMaster, la misma regla aplica: mantén medibles las funciones transversales (logging, auth, tracing) y trata las asignaciones por petición como un presupuesto que puedes auditar.

Arreglos que suelen dar retorno rápido

Una vez tengas vistas de heap y allocs desde pprof, prioriza cambios que reduzcan las asignaciones por petición. El objetivo no es trucos ingeniosos, sino hacer que el camino caliente cree menos objetos de vida corta, especialmente bajo carga.

Empieza por las mejoras seguras y aburridas

Si los tamaños son predecibles, prealoca. Si un endpoint suele devolver unos 200 items, crea el slice con capacidad 200 para que no crezca y se copie varias veces.

Evita construir strings en caminos calientes. fmt.Sprintf es cómodo, pero suele asignar. Para logging, prefiere campos estructurados y reutiliza un buffer pequeño cuando tenga sentido.

Si generas respuestas JSON grandes, considera streamarlas en vez de construir un gran []byte o string en memoria. Un patrón común en picos: entra la petición, lees un body grande, construyes una gran respuesta y la memoria salta hasta que el GC se pone al día.

Cambios rápidos que típicamente aparecen claramente en perfiles antes/después:

• Prealocar slices y maps cuando conoces el rango de tamaños
• Reemplazar formateo intensivo con fmt en el manejo de peticiones por alternativas más baratas
• Streamear respuestas JSON grandes (encode directo al response writer)
• Usar sync.Pool para objetos reutilizables de la misma forma (buffers, encoders) y devolverlos consistentemente
• Fijar límites de petición (tamaño de body, tamaño de payload, tamaño de página) para capar casos peores

Usa sync.Pool con cuidado

sync.Pool ayuda cuando reasignas repetidamente lo mismo, como un bytes.Buffer por petición. También puede perjudicar si almacenas objetos con tamaños impredecibles o no los reseteas, lo que mantiene arrays de respaldo grandes vivos.

Mide antes y después usando la misma carga:

• Captura un perfil de allocs durante la ventana del pico
• Aplica un cambio a la vez
• Ejecuta de nuevo la misma mezcla de peticiones y compara allocs/op totales
• Vigila la latencia tail, no solo la memoria

Si generas backends Go con AppMaster, estos arreglos siguen aplicando al código personalizado alrededor de handlers, integraciones y middleware. Ahí es donde suelen esconderse las asignaciones relacionadas con picos.

Errores comunes con pprof y falsas alarmas

La forma más rápida de perder el día es optimizar lo equivocado. Si el servicio va lento, empieza por CPU. Si lo matan por OOM, empieza por el heap. Si sobrevive pero el GC trabaja sin parar, mira la tasa de asignación y el comportamiento del GC.

Otra trampa es mirar solo top y darlo por hecho. top oculta contexto. Inspecciona siempre las pilas de llamada (o un flame graph) para ver quién llamó al asignador. La solución suele estar una o dos frames por encima de la función caliente.

También vigila la confusión entre inuse y churn. Una petición puede asignar 5 MB de objetos de corta vida, disparar GC extra y acabar con solo 200 KB en inuse. Si solo miras inuse, te pierdes el churn. Si solo miras asignaciones totales, puedes optimizar algo que nunca permanece y que no importa para el riesgo de OOM.

Comprobaciones rápidas antes de cambiar código:

• Confirma que estás en la vista correcta: heap inuse para retención, alloc_space/alloc_objects para churn
• Compara pilas, no solo nombres de funciones (encoding/json suele ser síntoma)
• Reproduce tráfico de forma realista: mismos endpoints, tamaños de payload, headers, concurrencia
• Captura un baseline y un perfil de pico, luego difféalos

Tests de carga poco realistas causan falsas alarmas. Si tu test envía cuerpos JSON muy pequeños pero producción envía payloads de 200 KB, optimizarás la ruta equivocada. Si tu test devuelve una fila, nunca verás el comportamiento de escaneo que aparece con 500 filas.

No persigas ruido. Si una función aparece solo en el perfil de pico (no en el baseline), es una pista sólida. Si aparece en ambos al mismo nivel, puede ser trabajo normal de fondo.

Un recorrido realista de incidente

Un lunes por la mañana sale una promo y tu API Go empieza a recibir 8x tráfico normal. El primer síntoma no es un crash. El RSS sube, el GC se vuelve más activo y la latencia p95 salta. El endpoint más caliente es GET /api/orders porque la app móvil lo refresca en cada apertura de pantalla.

Tomas dos snapshots: uno en un momento tranquilo (baseline) y otro durante el pico. Captura el mismo tipo de perfil de heap en ambos para que la comparación sea justa.

El flujo que funciona en el momento:

• Toma un perfil de heap baseline y anota RPS, RSS y p95 actuales
• Durante el pico, toma otro perfil de heap y además un perfil de asignaciones en la misma ventana de 1 a 2 minutos
• Compara los principales asignadores entre ambos y céntrate en lo que más creció
• Camina desde la función más pesada hacia sus llamantes hasta llegar al handler
• Haz un cambio pequeño, despliega en una sola instancia y vuelve a perfilar

En este caso, el perfil de pico mostró que la mayoría de las nuevas asignaciones venían del encoding JSON. El handler construía map[string]any por fila y luego hacía json.Marshal de un slice de maps. Cada petición creaba muchas strings y valores de interfaz de corta vida.

La corrección más pequeña y segura fue dejar de construir maps. Escanear las filas de la base de datos directamente en un struct tipado y codificar ese slice. No cambió nada más: mismos campos, misma forma de respuesta, mismos códigos de estado. Tras desplegar el cambio en una instancia, las asignaciones en la ruta JSON cayeron, el tiempo de GC disminuyó y la latencia se estabilizó.

Solo entonces despliegas gradualmente mientras vigilas memoria, GC y tasas de error. Si generas servicios en una plataforma no-code como AppMaster (appmaster.io), esto también recuerda mantener modelos de respuesta tipados y consistentes, porque ayuda a evitar costes ocultos de asignación.

Pasos siguientes para prevenir el próximo pico de memoria

Una vez estabilizado un pico, haz que el siguiente sea aburrido. Trata el perfilado como un ejercicio repetible.

Escribe un runbook corto que tu equipo pueda seguir cuando estén cansados. Debe decir qué capturar, cuándo capturarlo y cómo compararlo con un baseline conocido. Manténlo práctico: comandos exactos, dónde van los perfiles y qué es “normal” para tus principales asignadores.

Añade monitorización ligera para la presión de asignación antes de llegar a OOM: tamaño del heap, ciclos de GC por segundo y bytes asignados por petición. Detectar “asignaciones por petición arriba 30% semana a semana” suele ser más útil que esperar una alarma dura de memoria.

Mete checks más temprano con una pequeña prueba de carga en CI sobre un endpoint representativo. Cambios pequeños en la respuesta pueden duplicar las asignaciones si provocan copias extra, y es mejor detectarlo antes de que el tráfico de producción lo haga.

Si ejecutas un backend generado, exporta el código fuente y perfílalo igual. El código generado sigue siendo código Go, y pprof solo apuntará a funciones y líneas reales.

Si tus requisitos cambian a menudo, AppMaster (appmaster.io) puede ser una forma práctica de reconstruir y regenerar backends Go limpios a medida que la app evoluciona; luego perfila el código exportado bajo carga real antes de enviarlo.