StackPractices
intermediate Por Mathias Paulenko

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).

Mermaid flowchart LR diagram

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-blocking cambia 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ónOrigen de LogComplejidadUsar Cuando
Driver Dockerstdout/stderrBajaApps loguean a stdout
SidecarArchivos de logMediaApps escriben a archivos
Input HTTPHTTP POSTMediaApps envían logs vía HTTP
Input syslogsyslogMediaApps syslog legacy
Fluent Bit + Fluentdstdout/stderrMediaKubernetes / 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 copy para fan-out a varios destinos en lugar de duplicar bloques <match>.
  • Mantén flush_interval entre 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-blocking con max-buffer-size para 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_on o mete un reintento.
  • Dos bloques <match> con el mismo patrón esperando que ambos disparen — solo lo hace el primero; usa @type copy para 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 log para siempre.
  • Un único índice para todo: docker-logs crece sin límite; docker-logs-%Y%m%d te 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_size o vigila el crecimiento del buffer.
  • Hardcodear fluentd-address por entorno — gestiónalo con overrides como cualquier otra config específica de entorno (ver overrides de Docker Compose).

Lecturas Recomendadas

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.