Un pipeline de Fluentd, recopilar, transformar, enviar, se expresa por completo mediante un único archivo de configuración, construido a partir de un pequeño conjunto de directivas. Esta guía cubre qué hace cada directiva, cómo las conectan los tags y cómo comprobar una configuración antes de confiarle tráfico real.

Dónde vive el archivo de configuración

La distribución empaquetada propia de Fluentd se llama fluent-package (el sucesor del antiguo nombre td-agent; si lees documentación o tutoriales que mencionan td-agent, es el mismo proyecto bajo su marca anterior). Instalado de este modo, el archivo de configuración suele estar en /etc/fluent/fluentd.conf. Una distribución distinta, Calyptia Fluentd, mantenida por otra organización, usa su propia ruta. Consulta la documentación de tu método de instalación para conocer la ubicación exacta en lugar de suponer una.

Las tres directivas principales

• <source> define de dónde proceden los datos de log. Cada source declara un @type de plugin (tail para seguir un archivo, http para aceptar entradas por HTTP, y otros) y, de forma crítica, un tag, la etiqueta que lleva cada entrada de esta fuente a lo largo del resto del pipeline.
• <filter> procesa las entradas que coinciden con un patrón de tag dado, en el mismo lugar, antes de que lleguen a una salida. Usos comunes: añadir campos (enriquecimiento), eliminar campos (redacción) o descartar por completo las entradas que coinciden con un patrón.
• <match> es donde las entradas que coinciden se envían realmente. Igual que <filter>, se limita a un patrón de tag, pero en lugar de transformar datos en el mismo lugar, es la etapa de salida del pipeline: un destino y el @type de plugin que sabe escribir en él.

<source>
  @type tail
  path /var/log/apache2/access.log
  pos_file /var/log/fluent/apache-access.log.pos
  tag apache.access
  <parse>
    @type apache2
  </parse>
</source>

<filter apache.access>
  @type record_transformer
  remove_keys host
</filter>

<match apache.access>
  @type elasticsearch
  host localhost
  port 9200
  index_name fluentd-apache
</match>

Léelo de arriba abajo: la source sigue el log de acceso de Apache, analiza cada línea con el parser de formato de log de Apache incorporado de Fluentd y etiqueta cada entrada resultante como apache.access. El filter, limitado a ese mismo tag, elimina el campo host de cada entrada antes de que continúe. El match, también limitado a ese tag, envía las entradas (ya redactadas) a Elasticsearch.

Coincidencia de tags, no solo igualdad de tags

El patrón de tag de un bloque <filter> o <match> no tiene que ser una cadena exacta. apache.* coincide con cualquier tag que empiece por apache.; ** coincide con todo. Esto es lo que hace flexible el enrutamiento: un solo bloque <match **> puede actuar como destino comodín, mientras que patrones más específicos tratan fuentes concretas de forma distinta, redactando los datos de una fuente pero no los de otra, o enviando fuentes distintas a destinos completamente distintos.

Leer datos: el bloque anidado <parse>

Convertir una línea de log en bruto en datos clave-valor estructurados es trabajo de un parser, configurado como un bloque <parse> anidado dentro de una source (esta forma anidada es la sintaxis actual de Fluentd; algunos ejemplos de configuración antiguos muestran las opciones de parseo como parámetros planos directamente en la source, un estilo obsoleto que las versiones actuales ya no esperan). Fluentd incluye de serie parsers para formatos comunes: json, apache2, nginx, syslog, csv y un parser regexp para cualquier cosa que no coincida con un formato incorporado:

<parse>
  @type json
</parse>

Elegir el parser adecuado para una fuente es lo que convierte una línea de texto no estructurada en campos que puedes filtrar, enriquecer y consultar individualmente más adelante, en lugar de un único bloque de texto opaco.

Estructurar una configuración con includes

Cuando una configuración cubre varias fuentes, mantenerlo todo en un solo archivo se vuelve difícil de manejar. La directiva @include divide la configuración en varios archivos:

# fluentd.conf
@include apache.conf
@include containers.conf
@include outputs.conf

Cada archivo incluido contiene sus propios bloques <source>, <filter> o <match>, y Fluentd los ensambla como si estuvieran escritos en línea. Esto es puramente organizativo; no cambia cómo funcionan los tags, la coincidencia o el procesamiento, solo lo legible que se mantiene la configuración a medida que crece.

Valida antes de ejecutar

Antes de iniciar Fluentd de verdad, comprueba que una configuración está realmente bien formada:

fluentd --dry-run -c /etc/fluent/fluentd.conf

Esto analiza y valida la configuración sin procesar ningún dato de log real. Un dry run limpio no garantiza que el pipeline haga lo que pretendes, para eso hay que probar con datos reales, pero sí detecta errores de sintaxis evidentes y configuraciones erróneas de plugins antes de que aparezcan como un fallo de ejecución confuso.

Ejecútalo y míralo funcionar

Para pruebas manuales (a diferencia de ejecutar Fluentd como un servicio administrado en segundo plano, que es como normalmente se ejecuta en producción):

fluentd -c /etc/fluent/fluentd.conf

Con una source que sigue un archivo y un match que escribe en @type stdout, puedes ver las entradas fluir por el pipeline en tiempo real a medida que se escriben líneas nuevas en el archivo de origen, una forma rápida de confirmar que una source o un filter nuevos hacen lo que esperas antes de apuntarlos a un destino real.