Un pipeline Fluentd (collecter, transformer, expédier) s’exprime entièrement dans un seul fichier de configuration, construit à partir d’un petit ensemble de directives. Ce guide explique ce que fait chaque directive, comment les tags les relient, et comment vérifier une configuration avant de lui confier du trafic réel.

Où se trouve le fichier de configuration

La distribution packagée de Fluentd s’appelle fluent-package (le successeur de l’ancien nom td-agent ; si vous lisez de la documentation ou des tutoriels qui mentionnent td-agent, c’est le même projet sous son ancienne marque). Installé ainsi, le fichier de configuration se trouve typiquement dans /etc/fluent/fluentd.conf. Une autre distribution, Calyptia Fluentd, maintenue par une organisation différente, utilise son propre chemin. Consultez la documentation de votre méthode d’installation pour connaître l’emplacement exact plutôt que de le supposer.

Les trois directives principales

• <source> définit d’où viennent les données de log. Chaque source déclare un @type de plugin (tail pour suivre un fichier, http pour accepter des entrées en HTTP, et d’autres) et, point essentiel, un tag, l’étiquette que porte chaque entrée de cette source tout au long du reste du pipeline.
• <filter> traite sur place les entrées qui correspondent à un motif de tag donné, avant qu’elles n’atteignent une sortie. Usages courants : ajouter des champs (enrichissement), en retirer (masquage), ou écarter entièrement les entrées qui correspondent à un motif.
• <match> est l’endroit où les entrées correspondantes sont réellement envoyées. Comme <filter>, il est limité à un motif de tag, mais au lieu de transformer les données sur place, c’est l’étape de sortie du pipeline : une destination et le @type de plugin qui sait y écrire.

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

Lecture de haut en bas : la source suit le log d’accès d’Apache, analyse chaque ligne avec l’analyseur de format de log Apache intégré à Fluentd, et tague chaque entrée résultante apache.access. Le filtre, limité à ce même tag, retire le champ host de chaque entrée avant qu’elle n’aille plus loin. Le match, lui aussi limité à ce tag, expédie les entrées (désormais masquées) vers Elasticsearch.

La correspondance de tags, pas seulement l’égalité

Le motif de tag d’un bloc <filter> ou <match> n’a pas à être une chaîne exacte. apache.* correspond à tout tag commençant par apache. ; ** correspond à tout. C’est ce qui rend le routage flexible : un bloc <match **> peut servir de destination fourre-tout, tandis que des motifs plus spécifiques traitent certaines sources différemment, en masquant les données d’une source mais pas d’une autre, ou en expédiant différentes sources vers des destinations entièrement différentes.

Lire les données : le bloc imbriqué <parse>

Transformer une ligne de log brute en données structurées clé-valeur est le travail d’un analyseur (parser), configuré dans un bloc imbriqué <parse> à l’intérieur d’une source (cette forme imbriquée est la syntaxe actuelle de Fluentd ; d’anciens exemples de configuration montrent parfois les options d’analyse comme des paramètres à plat directement sur la source, ce qui est un style dépassé et n’est plus la façon dont les versions actuelles attendent qu’on l’écrive). Fluentd fournit d’office des analyseurs pour les formats courants : json, apache2, nginx, syslog, csv, ainsi qu’un analyseur regexp pour tout ce qui ne correspond pas à un format intégré :

<parse>
  @type json
</parse>

Choisir le bon analyseur pour une source est ce qui transforme une ligne de texte non structurée en champs que l’on peut filtrer, enrichir et interroger individuellement en aval, plutôt qu’un bloc de texte opaque.

Structurer une configuration avec des includes

Dès qu’une configuration couvre plusieurs sources, tout garder dans un seul fichier devient difficile à manier. La directive @include répartit la configuration sur plusieurs fichiers :

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

Chaque fichier inclus contient ses propres blocs <source>, <filter> ou <match>, et Fluentd les assemble comme s’ils étaient écrits en ligne. C’est purement organisationnel ; cela ne change ni les tags, ni la correspondance, ni le traitement, seulement la lisibilité de la configuration à mesure qu’elle grandit.

Valider avant d’exécuter

Avant de démarrer réellement Fluentd, vérifiez qu’une configuration est bien formée :

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

Ceci analyse et valide la configuration sans traiter de données de log réelles. Un dry run réussi ne garantit pas que le pipeline fait ce que vous voulez, cela demande encore des tests avec de vraies données, mais il détecte les erreurs de syntaxe pures et les mauvaises configurations de plugins avant qu’elles ne se manifestent par une panne d’exécution déroutante.

L’exécuter et le regarder fonctionner

Pour des tests manuels (par opposition à l’exécution de Fluentd comme service d’arrière-plan géré, ce qui est sa façon normale de tourner en production) :

fluentd -c /etc/fluent/fluentd.conf

Avec une source qui suit un fichier et un match qui écrit vers @type stdout, vous pouvez voir les entrées traverser le pipeline en temps réel au fur et à mesure que de nouvelles lignes sont écrites dans le fichier source, ce qui est un moyen rapide de confirmer qu’une nouvelle source ou un nouveau filtre fait bien ce que vous attendez avant de le pointer vers une vraie destination.