Centraliza Logs de Contenedores con Fluentd y Docker
Recolecta, filtra y reenvía logs de contenedores Docker a Elasticsearch, S3 o stdout usando Fluentd como driver de logging o sidecar.
Visión General
Los contenedores Docker escriben sus logs en stdout y stderr, y por defecto el daemon los vuelca en archivos JSON en el host — archivos difíciles de consultar, fáciles de perder, y repartidos por cada máquina que ejecutes. Fluentd es un recolector de logs open-source que se interpone entre tus contenedores y tu almacenamiento: recibe cada evento de log, lo enriquece con metadatos como nombre e imagen del contenedor, opcionalmente lo parsea y filtra, y después lo reenvía a Elasticsearch, S3, Kafka o simplemente stdout.
Esta receta cubre las dos formas de llevar logs de contenedores a Fluentd — el driver de logging fluentd integrado, que captura stdout/stderr a nivel del daemon sin tocar la app, y el patrón sidecar, que hace tail de archivos de log a través de un volumen compartido para apps que no loguean a stdout. Al final tendrás un stack Fluentd → Elasticsearch → Kibana funcional que podrás consultar en la pestaña Discover de Kibana. Cada config de esta página está en el repo complementario, lista para ejecutar.
Cuándo Usar
- Necesitas agregación centralizada de logs entre tus contenedores y hosts
- Quieres enriquecer logs con metadatos de contenedor (nombre, imagen, labels)
- Necesitas filtrar o transformar logs antes de almacenarlos
- Reenvías logs a Elasticsearch, S3, Kafka u otros destinos
- Tu equipo consulta logs en Kibana o necesita retención a largo plazo fuera del host
Sáltate Fluentd cuando una opción más simple encaje: docker logs + el driver JSON para depurar en un solo host, o el stack Grafana/Loki si ya estás invertido en ese ecosistema — mira la guía de observabilidad con Grafana para la comparación.
Solución
Fluentd como driver de logging de Docker
# Iniciar Fluentd primero — los contenedores con el driver fallan si no está arriba
docker run -d \
--name fluentd \
-p 24224:24224 \
-p 24224:24224/udp \
-v $(pwd)/fluentd.conf:/fluentd/etc/fluent.conf \
fluent/fluentd:v1.16
# Ejecutar contenedores con el driver de logs fluentd
docker run -d \
--name api \
--log-driver fluentd \
--log-opt fluentd-address=localhost:24224 \
--log-opt tag="docker.{{.Name}}" \
--log-opt mode=non-blocking \
--log-opt max-buffer-size=4m \
my-api:latest
De esas opciones, dos hacen trabajo real en producción. Con mode=non-blocking el contenedor sigue corriendo aunque Fluentd vaya lento o esté caído — deja el modo bloqueante por defecto y un tropiezo de Fluentd congela las escrituras de tu app a stdout. max-buffer-size pone el techo al buffer por contenedor que el daemon retiene mientras Fluentd no responde; cuando se llena, las líneas empiezan a descartarse — lo cual es mejor que una app congelada. Configura las dos, siempre.
Archivo de configuración de Fluentd
# fluentd.conf
# Source: recibir logs del driver fluentd de Docker
<source>
@type forward
port 24224
bind 0.0.0.0
</source>
# Filter: añadir metadatos de contenedor
<filter docker.**>
@type record_transformer
<record>
hostname ${hostname}
source "docker"
</record>
</filter>
# Filter: parsear logs JSON emitidos por la aplicación
<filter docker.**>
@type parser
key_name log
reserve_data true
<parse>
@type json
</parse>
</filter>
# Match: fan-out a Elasticsearch Y stdout
# Fluentd enruta cada evento al PRIMER <match> que coincida —
# dos bloques <match docker.**> separados no se ejecutan ambos.
# @type copy reparte cada evento a todos sus hijos <store>.
<match docker.**>
@type copy
<store>
@type elasticsearch
host elasticsearch
port 9200
index_name docker-logs-%Y%m%d
type_name _doc
flush_interval 5s
</store>
<store>
@type stdout
</store>
</match>
Hay una trampa que le toca a todo el mundo una vez: los bloques <match> se evalúan en orden y cada evento termina en el primero que encaje — escribir dos bloques <match docker.**> seguidos no envía a ambos. Para que el evento llegue a ambos destinos: @type copy con un <store> por destino. Y el nombre de índice diario (docker-logs-%Y%m%d) no es capricho: mantiene los índices de Elasticsearch manejables, mientras que un único índice por contenedor es el patrón que se rompe a escala.
Docker Compose con Fluentd + Elasticsearch + Kibana
# docker-compose.yml
services:
fluentd:
image: fluent/fluentd:v1.16
ports:
- "24224:24224"
- "24224:24224/udp"
volumes:
- ./fluentd.conf:/fluentd/etc/fluent.conf
depends_on:
- elasticsearch
networks:
- logging
deploy:
resources:
limits:
memory: 512M
elasticsearch:
image: docker.elastic.co/elasticsearch/elasticsearch:8.13.0
environment:
- discovery.type=single-node
- xpack.security.enabled=false
ports:
- "9200:9200"
networks:
- logging
kibana:
image: docker.elastic.co/kibana/kibana:8.13.0
ports:
- "5601:5601"
environment:
- ELASTICSEARCH_HOSTS=http://elasticsearch:9200
depends_on:
- elasticsearch
networks:
- logging
api:
build: .
logging:
driver: fluentd
options:
fluentd-address: localhost:24224
tag: docker.api
mode: non-blocking
max-buffer-size: 4m
depends_on:
- fluentd
networks:
- logging
networks:
logging:
driver: bridge
Fíjate en la red logging dedicada: si ya separas servicios en bridges frontend y backend, dale al plano de logging el suyo igual que aislarías cualquier dependencia interna (ver aislamiento de redes Docker). El límite de memoria de Fluentd tampoco es decoración — ante un pico de logs el buffer se dispara, y un Fluentd sin límites acaba OOM-killed a mitad de un flush.
Patrón sidecar para recolección de archivos de log
# docker-compose.yml — el sidecar lee archivos de log desde volumen compartido
services:
api:
build: .
volumes:
- api-logs:/var/log/app
# La app escribe logs a /var/log/app/app.log
fluentd-sidecar:
image: fluent/fluentd:v1.16
volumes:
- api-logs:/var/log/app
- ./fluentd-sidecar.conf:/fluentd/etc/fluent.conf
# Fluentd hace tail del archivo de log
volumes:
api-logs:
# fluentd-sidecar.conf — tail de archivos de log
<source>
@type tail
path /var/log/app/app.log
pos_file /var/log/app/app.log.pos
tag app.api
<parse>
@type json
time_key timestamp
time_format %Y-%m-%dT%H:%M:%S.%LZ
</parse>
</source>
<match app.**>
@type elasticsearch
host elasticsearch
port 9200
index_name app-logs-%Y%m%d
flush_interval 5s
</match>
El pos_file es el detalle que hace que esto funcione tras reinicios: Fluentd registra ahí su offset de lectura, así que un sidecar reiniciado retoma donde quedó en lugar de re-ingerir el archivo entero (o peor, saltarse entradas). Algo que no se ve arriba: monta ese volumen como read-only del lado del sidecar. Fluentd jamás escribe ahí — :ro cuesta cero y suma seguridad.
Reenviar a AWS S3
# fluentd.conf — output a S3 para archivo a largo plazo
<match docker.**>
@type s3
aws_key_id "#{ENV['AWS_ACCESS_KEY_ID']}"
aws_sec_key "#{ENV['AWS_SECRET_ACCESS_KEY']}"
s3_bucket my-log-bucket
s3_region us-east-1
path logs/
buffer_path /var/log/fluent/s3
time_slice_format %Y%m%d
time_slice_wait 10m
flush_interval 30s
</match>
S3 es el destino de almacenamiento frío — barato, duradero, consultable después con Athena o con una regla de lifecycle hacia Glacier. Saca las credenciales de variables de entorno (o de un rol IAM en EC2/ECS) en lugar de hardcodearlas, y combínalo con el store de ES vía @type copy si quieres búsqueda caliente más archivo.
Logging JSON estructurado desde tu app
// Node.js — logging estructurado para Fluentd
const logger = {
info(message, meta = {}) {
console.log(JSON.stringify({
level: "info",
message,
timestamp: new Date().toISOString(),
service: "api",
...meta
}));
},
error(message, meta = {}) {
console.error(JSON.stringify({
level: "error",
message,
timestamp: new Date().toISOString(),
service: "api",
...meta
}));
}
};
logger.info("Request received", { method: "GET", path: "/users", duration: 12 });
import json
import logging
class JsonFormatter(logging.Formatter):
def format(self, record):
log_data = {
"level": record.levelname.lower(),
"message": record.getMessage(),
"timestamp": self.formatTime(record),
"service": "api",
}
return json.dumps(log_data)
handler = logging.StreamHandler()
handler.setFormatter(JsonFormatter())
logging.basicConfig(level=logging.INFO, handlers=[handler])
Ese JSON es justo lo que el bloque parser del <filter> desempaqueta — Fluentd convierte cada línea en campos reales, así que queries de Kibana como level:error AND service:api funcionan directo en vez de grepear texto de mensajes. Hay un tratamiento completo de este patrón en la guía de logging estructurado.
Explicación
Con el driver fluentd, el stdout/stderr del contenedor viaja hasta Fluentd por el protocolo Forward — compacto, binario, sobre TCP, y nativo de los propios plugins de Fluentd. Cada línea de log aparece como un evento cuyo tag sale directo de --log-opt tag= — docker.{{.Name}} produce docker.api, docker.worker, y así. Desde ahí el pipeline no cambia de forma: source (ingesta) → filter (transformar/enriquecer) → match (output).
Como sources puedes elegir forward (el driver de Docker), tail para seguir archivos, http para un endpoint de ingesta, o syslog. En filters tienes record_transformer para añadir campos, parser para desempaquetar formatos, y grep para descartar líneas que no te interesan. Los outputs cubren elasticsearch, s3, kafka, stdout y file.
Conceptos clave:
- tag: etiqueta flujos de log para enrutamiento — cada filter y match depende de él
- buffer: Fluentd almacena eventos en buffer antes de hacer flush al destino, así una caída de Elasticsearch encola logs en disco en lugar de descartarlos
- flush_interval: cada cuánto se envían los logs en buffer — valores más bajos significan entrega casi en tiempo real pero más peticiones y rotación de índices
- blocking vs non-blocking: es una preocupación del lado de Docker, no de Fluentd — el driver almacena en el daemon y
mode=non-blockingcambia posible pérdida de logs por disponibilidad de la app
Driver vs sidecar: elige el driver cuando tu app escribe a stdout (el 99% de las apps containerizadas debería). Elige el sidecar cuando la app insiste en escribir a archivos de log — apps legacy, JVMs con appenders de archivo — o cuando necesitas config de Fluentd por app sin tocar el daemon. En Kubernetes, ninguno de los dos patrones es típico: Fluent Bit como DaemonSet reenviando a un agregador Fluentd es la topología estándar, porque observa metadatos de pods nativamente.
Verificar que el pipeline funciona
# 1. Fluentd está escuchando
docker logs fluentd | tail -5
# 2. Enviar un evento de prueba por el protocolo Forward
echo '{"key":"value"}' | fluent-cat docker.test -h localhost -p 24224
# 3. El índice existe y crece
curl -s "localhost:9200/_cat/indices?v" | grep docker-logs
# 4. Consultar los documentos que llegaron
curl -s "localhost:9200/docker-logs-*/_search?q=service:api&size=3" | jq .hits.hits
Si los eventos nunca llegan a ES, los sospechosos habituales son el tag (¿docker.** realmente coincide con tu --log-opt tag?), el tag por defecto docker.{{.ID}} de Docker produciendo tags que no matchean, o un fallo de parse que mandó registros al label @ERROR de Fluentd — docker logs fluentd muestra los tres.
Variantes
| Patrón | Origen de Log | Complejidad | Usar Cuando |
|---|---|---|---|
| Driver Docker | stdout/stderr | Baja | Apps loguean a stdout |
| Sidecar | Archivos de log | Media | Apps escriben a archivos |
| Input HTTP | HTTP POST | Media | Apps envían logs vía HTTP |
| Input syslog | syslog | Media | Apps syslog legacy |
| Fluent Bit + Fluentd | stdout/stderr | Media | Kubernetes / flotas grandes |
Mejores Prácticas
- Usa el driver de logging Fluentd para apps que loguean a stdout/stderr, el sidecar para apps que escriben a archivos.
- Parsea logs siempre como JSON — el texto no estructurado es casi imposible de consultar en Elasticsearch.
- Añade metadatos (hostname, nombre de servicio, nombre de contenedor) con
record_transformer; los IDs crudos de contenedor no le sirven a nadie. - Usa buffer en cada output; usa
@type copypara fan-out a varios destinos en lugar de duplicar bloques<match>. - Mantén
flush_intervalentre 5 y 30 segundos según qué tan frescos necesites los datos, y cambia a índices diarios (docker-logs-%Y%m%d) desde el primer día. - Configura
--log-opt mode=non-blockingconmax-buffer-sizepara que un Fluentd lento no pueda congelar tus contenedores. - Pon Fluentd en su propia red y acota su memoria — es infraestructura, y cuando muere también es tu única ventana al porqué.
- Monitorea el propio Fluentd (volumen de logs, longitud de cola del buffer, errores de output); expone sus métricas vía el endpoint
monitor_agent.
Errores Comunes
- Levantar las apps antes que Fluentd — el driver fluentd lo necesita vivo al arrancar, así que directamente no suben; fija el orden con
depends_ono mete un reintento. - Dos bloques
<match>con el mismo patrón esperando que ambos disparen — solo lo hace el primero; usa@type copypara fan-out. - Dejar
mode=blocking(el default): si Fluentd va lento o cae, tus contenedores se congelan en escrituras a stdout. - Logs sin parsear llegando a Elasticsearch — “funciona” técnicamente pero te deja grepeando campos
logpara siempre. - Un único índice para todo:
docker-logscrece sin límite;docker-logs-%Y%m%dte permite aplicar retención borrando índices viejos. - Sin límite de memoria en Fluentd: un pico de logs agranda el buffer hasta que el kernel mata Fluentd a mitad de un flush.
- Archivos de buffer de Fluentd sin rotar llenando el disco en semanas — define
total_limit_sizeo vigila el crecimiento del buffer. - Hardcodear
fluentd-addresspor entorno — gestiónalo con overrides como cualquier otra config específica de entorno (ver overrides de Docker Compose).
Lecturas Recomendadas
- Documentación de Fluentd — input forward, outputs, buffering
- Docker Docs — Fluentd logging driver — referencia de opciones del driver
- Docker Docs — Configurar drivers de logging — modos blocking y dimensionado del buffer
Ver También
Preguntas frecuentes
¿Qué pasa si Fluentd está caído cuando se usa el driver de logging?
En modo bloqueante (el default), Docker congela el proceso del contenedor en las escrituras a stdout hasta que Fluentd se recupera. Con mode=non-blocking el daemon retiene logs en un buffer por contenedor hasta max-buffer-size; pasado ese tope se pierden. Usa non-blocking en producción — perder algunos logs es mejor que congelar la app — y dimensiona max-buffer-size para cubrir la ventana de reinicio esperada de Fluentd.
Fluentd vs Fluent Bit — ¿cuál debo usar?
Fluent Bit es el colector más ligero (basado en C, ~2MB) pensado para roles de edge como un DaemonSet de Kubernetes. Fluentd es más rico (basado en Ruby) con ~1000 plugins pero más pesado (~40MB+). La topología común en producción es Fluent Bit en los nodos recolectando y reenviando a un agregador Fluentd que hace el filtrado y enrutamiento pesado. Para un setup Docker de un solo host, Fluentd solo es suficiente.
¿Cómo pruebo mi configuración de Fluentd?
# Enviar un log de prueba por el protocolo Forward
echo '{"key":"value"}' | fluent-cat docker.test -h localhost -p 24224
# Revisar los logs de Fluentd en busca de errores de parse/ruta
docker logs fluentd
# Dry-run de la config antes de recargar
fluentd --dry-run -c /fluentd/etc/fluent.conf
¿Puedo usar Fluentd con Docker Swarm?
Sí. Despliega Fluentd como servicio global (una réplica por nodo) y apunta el --log-driver fluentd de cada servicio a la instancia Fluentd del nodo. Pon el tier agregador en una red overlay para que el reenvío entre nodos funcione. Ten en cuenta que el driver a nivel daemon no sabe de servicios de Swarm — etiqueta por nombre de servicio con variantes de {{.Name}} o con labels.
Recursos Relacionados
Aislamiento de Red Docker y Seguridad Entre Contenedores
Asegura la comunicación entre contenedores con redes Docker personalizadas, segmentación de red y políticas de control de acceso.
RecipeConfiguración de Docker Health Check para Confiabilidad
Configura HEALTHCHECK de Docker con curl, wget o scripts propios para detectar contenedores que dejan de responder, no solo los que fallan.
RecipeSobrescribe la Configuración de Docker Compose por Entorno
Cómo usar archivos override de Docker Compose para configuraciones por entorno: desarrollo, test, staging y producción, con profiles y secrets.
GuideGuía Completa de Observabilidad con el Stack de Grafana
Monta el stack completo de observabilidad de Grafana: Prometheus, Loki, Tempo, Alloy y Grafana con un solo docker-compose, correlación de señales y alertado por SLO.
GuideLogging Estructurado: JSON, IDs de Correlación y Agregación
Logging estructurado con salida JSON, IDs de correlación y niveles de log. Python structlog, Node.js pino, Java SLF4J y stacks de agregación ELK y Loki.
RecipeExpón métricas de aplicación con Python y Prometheus
Construye un exporter de métricas Prometheus en Python con prometheus_client. Cubre counters, gauges, histograms, summaries e integración con Flask y FastAPI.