Aide-mémoire Fluentd

Installation

Plateforme	Commande
Ubuntu/Debian (td-agent)	`curl -fsSL https://toolbelt.treasuredata.com/sh/install-ubuntu-jammy-td-agent4.sh \
RHEL/CentOS	`curl -L https://toolbelt.treasuredata.com/sh/install-redhat-td-agent4.sh \
macOS	`brew install fluentd`
Ruby Gem	`gem install fluentd`
Docker	`docker pull fluent/fluentd:latest`
Kubernetes	Déployer en tant que DaemonSet (voir la section Configuration)

Commandes de base

Commande	Description
`fluentd -c fluent.conf`	Démarrer Fluentd avec un fichier de configuration spécifié
`fluentd -c fluent.conf -vv`	Exécuter avec une sortie de débogage verbeuse
`fluentd -c fluent.conf --dry-run`	Valider la configuration sans démarrer
`fluentd --setup ./fluent`	Créer la structure de répertoires de configuration par défaut
`fluentd --version`	Afficher les informations de version de Fluentd
`sudo systemctl start td-agent`	Démarrer le service td-agent (Linux)
`sudo systemctl stop td-agent`	Arrêter le service td-agent
`sudo systemctl restart td-agent`	Redémarrer le service td-agent
`sudo systemctl status td-agent`	Vérifier le statut du service td-agent
`sudo systemctl reload td-agent`	Recharger la configuration sans redémarrer
`sudo systemctl enable td-agent`	Activer td-agent au démarrage
`sudo journalctl -u td-agent -f`	Suivre les journaux du service td-agent en temps réel
`echo ’{“msg”:“test”}’ \	fluent-cat debug.test`
`curl -X POST -d 'json={"event":"test"}' http://localhost:8888/test.cycle`	Envoyer le journal de test HTTP
`td-agent-gem list \	grep fluent-plugin`

Utilisation avancée

Commande	Description
`fluentd -c fluent.conf -d /var/run/fluentd.pid`	Exécuter Fluentd en mode daemon avec un fichier PID
`fluentd -c fluent.conf -o /var/log/fluentd.log`	Exécuter avec sortie vers un fichier journal spécifique
`fluentd -c fluent.conf --workers 4`	Exécuter avec plusieurs processus worker
`fluentd -c fluent.conf -vvv`	Exécuter avec la journalisation au niveau de trace pour le débogage
`fluentd --show-plugin-config=input:tail`	Afficher les options de configuration pour le plugin spécifique
`td-agent-gem install fluent-plugin-elasticsearch`	Installer le plugin de sortie Elasticsearch
`td-agent-gem install fluent-plugin-kafka -v 0.17.5`	Installer une version spécifique du plugin Kafka
`td-agent-gem update fluent-plugin-s3`	Mettre à jour le plugin S3 vers la dernière version
`td-agent-gem uninstall fluent-plugin-mongo`	Supprimer le plugin MongoDB
`td-agent-gem search -r fluent-plugin`	Rechercher des plugins disponibles dans le dépôt
`fluent-cat --host 192.168.1.100 --port 24224 app.logs`	Envoyer les logs à l’instance Fluentd distante
`fluent-cat app.logs < /path/to/logfile.json`	Envoyer le contenu du fichier journal à Fluentd
`docker run -d -p 24224:24224 -v /data/fluentd:/fluentd/etc fluent/fluentd`	Exécuter Fluentd dans Docker avec configuration montée
`sudo kill -USR1 $(cat /var/run/td-agent/td-agent.pid)`	Recharger gracieusement Fluentd (rouvrir les fichiers de log)
`sudo kill -USR2 $(cat /var/run/td-agent/td-agent.pid)`	Rouvrir les fichiers de log Fluentd sans rechargement

Configuration

Emplacements des fichiers de configuration principaux

td-agent (Linux): /etc/td-agent/td-agent.conf
Installation Gem: ./fluent/fluent.conf
Docker: /fluentd/etc/fluent.conf

Structure de configuration de base

# Source: Input plugins
<source>
  @type forward
  port 24224
  bind 0.0.0.0
</source>

# Filter: Process/transform logs
<filter app.**>
  @type record_transformer
  <record>
    hostname "#{Socket.gethostname}"
    tag ${tag}
  </record>
</filter>

# Match: Output plugins
<match app.**>
  @type elasticsearch
  host elasticsearch.local
  port 9200
  index_name fluentd
  type_name fluentd
</match>

Plugins Source (Entrée)

# Forward input (receive from other Fluentd instances)
<source>
  @type forward
  port 24224
  bind 0.0.0.0
</source>

# Tail log files
<source>
  @type tail
  path /var/log/nginx/access.log
  pos_file /var/log/td-agent/nginx-access.pos
  tag nginx.access
  <parse>
    @type nginx
  </parse>
</source>

# HTTP input
<source>
  @type http
  port 8888
  bind 0.0.0.0
  body_size_limit 32m
  keepalive_timeout 10s
</source>

# Syslog input
<source>
  @type syslog
  port 5140
  bind 0.0.0.0
  tag system.syslog
</source>

Plugins Filtre (Traitement)

# Add/modify record fields
<filter app.**>
  @type record_transformer
  <record>
    hostname "#{Socket.gethostname}"
    environment production
    timestamp ${time}
  </record>
</filter>

# Parse unstructured logs
<filter app.logs>
  @type parser
  key_name message
  <parse>
    @type json
  </parse>
</filter>

# Grep filter (include/exclude)
<filter app.**>
  @type grep
  <regexp>
    key level
    pattern /^(ERROR|FATAL)$/
  </regexp>
</filter>

# Modify tag
<match app.raw.**>
  @type rewrite_tag_filter
  <rule>
    key level
    pattern /^ERROR$/
    tag app.error.${tag}
  </rule>
</match>

Plugins Match (Sortie)

# Elasticsearch output
<match app.**>
  @type elasticsearch
  host elasticsearch.local
  port 9200
  logstash_format true
  logstash_prefix fluentd
  <buffer>
    @type file
    path /var/log/fluentd/buffer/elasticsearch
    flush_interval 10s
    retry_max_interval 300s
  </buffer>
</match>

# S3 output
<match logs.**>
  @type s3
  aws_key_id YOUR_AWS_KEY_ID
  aws_sec_key YOUR_AWS_SECRET_KEY
  s3_bucket your-bucket-name
  s3_region us-east-1
  path logs/
  time_slice_format %Y%m%d%H
  <buffer time>
    timekey 3600
    timekey_wait 10m
  </buffer>
</match>

# File output
<match debug.**>
  @type file
  path /var/log/fluentd/output
  <buffer>
    timekey 1d
    timekey_use_utc true
  </buffer>
</match>

# Forward to another Fluentd
<match forward.**>
  @type forward
  <server>
    host 192.168.1.100
    port 24224
  </server>
  <buffer>
    @type file
    path /var/log/fluentd/buffer/forward
  </buffer>
</match>

# Stdout (debugging)
<match debug.**>
  @type stdout
</match>

Configuration du tampon

<match pattern.**>
  @type elasticsearch
  
  # File buffer with advanced settings
  <buffer>
    @type file
    path /var/log/fluentd/buffer
    
    # Flush settings
    flush_mode interval
    flush_interval 10s
    flush_at_shutdown true
    
    # Retry settings
    retry_type exponential_backoff
    retry_wait 10s
    retry_max_interval 300s
    retry_timeout 72h
    retry_max_times 17
    
    # Chunk settings
    chunk_limit_size 5M
    queue_limit_length 32
    overflow_action drop_oldest_chunk
    
    # Compression
    compress gzip
  </buffer>
</match>

# Memory buffer for high-performance
<match fast.**>
  @type forward
  <buffer>
    @type memory
    flush_interval 5s
    chunk_limit_size 1M
    queue_limit_length 64
  </buffer>
</match>

Configuration multi-worker

<system>
  workers 4
  root_dir /var/log/fluentd
</system>

# Worker-specific sources
<worker 0>
  <source>
    @type forward
    port 24224
  </source>
</worker>

<worker 1-3>
  <source>
    @type tail
    path /var/log/app/*.log
    tag app.logs
  </source>
</worker>

Routage basé sur les étiquettes

# Route to different pipelines using labels
<source>
  @type forward
  @label @mainstream
</source>

<source>
  @type tail
  path /var/log/secure.log
  @label @security
</source>

<label @mainstream>
  <filter **>
    @type record_transformer
    <record>
      pipeline mainstream
    </record>
  </filter>
  
  <match **>
    @type elasticsearch
    host es-main
  </match>
</label>

<label @security>
  <filter **>
    @type grep
    <regexp>
      key message
      pattern /authentication failure/
    </regexp>
  </filter>
  
  <match **>
    @type s3
    s3_bucket security-logs
  </match>
</label>

Cas d’utilisation courants

Cas d’utilisation 1 : Collecter les logs Nginx vers Elasticsearch

# Install Elasticsearch plugin
sudo td-agent-gem install fluent-plugin-elasticsearch

# Configure Fluentd
sudo tee /etc/td-agent/td-agent.conf > /dev/null <<'EOF'
<source>
  @type tail
  path /var/log/nginx/access.log
  pos_file /var/log/td-agent/nginx-access.pos
  tag nginx.access
  <parse>
    @type nginx
  </parse>
</source>

<match nginx.access>
  @type elasticsearch
  host localhost
  port 9200
  logstash_format true
  logstash_prefix nginx
  <buffer>
    flush_interval 10s
  </buffer>
</match>
EOF

# Restart td-agent
sudo systemctl restart td-agent

# Verify logs are flowing
sudo journalctl -u td-agent -f

Cas d’utilisation 2 : Collection de logs Kubernetes

# Deploy Fluentd DaemonSet
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: ServiceAccount
metadata:
  name: fluentd
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: fluentd
rules:
- apiGroups: [""]
  resources: ["pods", "namespaces"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: fluentd
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: fluentd
subjects:
- kind: ServiceAccount
  name: fluentd
  namespace: kube-system
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: fluentd
  namespace: kube-system
spec:
  selector:
    matchLabels:
      k8s-app: fluentd-logging
  template:
    metadata:
      labels:
        k8s-app: fluentd-logging
    spec:
      serviceAccountName: fluentd
      containers:
      - name: fluentd
        image: fluent/fluentd-kubernetes-daemonset:v1-debian-elasticsearch
        env:
        - name: FLUENT_ELASTICSEARCH_HOST
          value: "elasticsearch.logging.svc.cluster.local"
        - name: FLUENT_ELASTICSEARCH_PORT
          value: "9200"
        volumeMounts:
        - name: varlog
          mountPath: /var/log
        - name: varlibdockercontainers
          mountPath: /var/lib/docker/containers
          readOnly: true
      volumes:
      - name: varlog
        hostPath:
          path: /var/log
      - name: varlibdockercontainers
        hostPath:
          path: /var/lib/docker/containers
EOF

# Check DaemonSet status
kubectl get daemonset -n kube-system fluentd
kubectl logs -n kube-system -l k8s-app=fluentd-logging --tail=50

Cas d’utilisation 3 : Transférer les logs vers S3 avec rotation

# Install S3 plugin
sudo td-agent-gem install fluent-plugin-s3

# Configure S3 output
sudo tee /etc/td-agent/td-agent.conf > /dev/null <<'EOF'
<source>
  @type tail
  path /var/log/app/*.log
  pos_file /var/log/td-agent/app.pos
  tag app.logs
  <parse>
    @type json
  </parse>
</source>

<match app.logs>
  @type s3
  
  aws_key_id YOUR_AWS_ACCESS_KEY
  aws_sec_key YOUR_AWS_SECRET_KEY
  s3_bucket my-application-logs
  s3_region us-east-1
  
  path logs/%Y/%m/%d/
  s3_object_key_format %{path}%{time_slice}_%{index}.%{file_extension}
  
  <buffer time>
    @type file
    path /var/log/td-agent/s3
    timekey 3600
    timekey_wait 10m
    chunk_limit_size 256m
  </buffer>
  
  <format>
    @type json
  </format>
</match>
EOF

# Restart and verify
sudo systemctl restart td-agent
sudo systemctl status td-agent

Cas d’utilisation 4 : Routage de logs multi-destinations

# Configure routing to multiple destinations
sudo tee /etc/td-agent/td-agent.conf > /dev/null <<'EOF'
<source>
  @type tail
  path /var/log/app/application.log
  pos_file /var/log/td-agent/app.pos
  tag app.logs
  <parse>
    @type json
  </parse>
</source>

# Copy logs to multiple destinations
<match app.logs>
  @type copy
  
  # Send to Elasticsearch
  <store>
    @type elasticsearch
    host elasticsearch.local
    port 9200
    logstash_format true
  </store>
  
  # Send to S3 for archival
  <store>
    @type s3
    s3_bucket app-logs-archive
    path logs/
    <buffer time>
      timekey 86400
    </buffer>
  </store>
  
  # Send errors to Slack
  <store>
    @type grep
    <regexp>
      key level
      pattern /^ERROR$/
    </regexp>
    @type slack
    webhook_url https://hooks.slack.com/services/YOUR/WEBHOOK/URL
    channel alerts
    username fluentd
  </store>
</match>
EOF

sudo systemctl restart td-agent

Cas d’utilisation 5 : Intégration de surveillance des performances d’application

# Configure APM log forwarding
sudo tee /etc/td-agent/td-agent.conf > /dev/null <<'EOF'
<source>
  @type tail
  path /var/log/app/*.log
  pos_file /var/log/td-agent/app.pos
  tag app.logs
  <parse>
    @type json
    time_key timestamp
    time_format %Y-%m-%dT%H:%M:%S.%NZ
  </parse>
</source>

# Enrich logs with metadata
<filter app.logs>
  @type record_transformer
  <record>
    hostname "#{Socket.gethostname}"
    environment ${ENV['ENVIRONMENT'] || 'production'}
    service_name myapp
    trace_id ${record['trace_id']}
  </record>
</filter>

# Calculate response time metrics
<filter app.logs>
  @type prometheus
  <metric>
    name http_request_duration_seconds
    type histogram
    desc HTTP request duration
    key response_time
  </metric>
</filter>

# Forward to APM system
<match app.logs>
  @type http
  endpoint http://apm-server:8200/intake/v2/events
  <buffer>
    flush_interval 5s
  </buffer>
</match>
EOF

sudo systemctl restart td-agent

Meilleures pratiques

Utiliser des tampons basés sur des fichiers pour la production : Les tampons mémoire sont plus rapides, mais les tampons de fichiers empêchent la perte de données lors des redémarrages ou des plantages. Toujours utiliser des tampons de fichiers avec des paramètres de nouvelle tentative appropriés pour les logs critiques.
Implémenter une rotation et une rétention de logs appropriées : Configurer

Note: Some sections (3-20) were left untranslated as no specific text was provided in the original request.pos_filepour les entrées de tail et définir des valeurs appropriéestimekeydans les tampons pour prévenir les problèmes d’espace disque. Utiliserrotate_ageetrotate_sizepour les sorties de fichiers.

Étiqueter les logs de manière hiérarchique : Utiliser des étiquettes avec notation par points (par ex., app.production.web) pour permettre un routage et un filtrage flexibles. Cela permet de faire correspondre des modèles comme app.**ou app.production.*.
Surveiller les performances de Fluentd : Suivre la longueur de la file d’attente des tampons, les nombres de nouvelles tentatives et les taux d’émission. Utiliser le plugin Prometheus ou la surveillance intégrée pour détecter les goulots d’étranglement avant qu’ils ne provoquent une perte de données.
Sécuriser les données sensibles : Utiliser @type secure_forwardpour la transmission de logs chiffrés, filtrer les champs sensibles avec record_modifier, et restreindre les permissions de fichiers sur les fichiers de configuration contenant des identifiants.
Tester les modifications de configuration : Toujours utiliser --dry-runpour valider la syntaxe de configuration avant le déploiement. Tester la logique de routage avec de petits volumes de logs avant d’appliquer en production.
Utiliser le mode multi-worker avec discernement : Activer les workers pour les opérations gourmandes en CPU (analyse, filtrage) mais être conscient que certains plugins ne prennent pas en charge le mode multi-worker. Commencer avec 2-4 workers et surveiller l’utilisation du CPU.
Implémenter la dégradation gracieuse : Configurer overflow_actiondans les tampons pour gérer la contre-pression (utiliser drop_oldest_chunkou blockselon vos besoins). Définir des valeurs retry_timeoutraisonnables pour éviter les nouvelles tentatives infinies.
Séparer les préoccupations avec des étiquettes : Utiliser des directives @labelpour créer des pipelines de traitement isolés pour différents types de logs. Cela améliore la maintenabilité et empêche le routage non intentionnel.
Maintenir les plugins à jour : Mettre à jour régulièrement Fluentd et les plugins pour obtenir des correctifs de sécurité et des améliorations de performances. Épingler les versions de plugins en production pour assurer la cohérence.

Résolution des problèmes

Problème	Solution
Fluentd won’t start	Check syntax: `fluentd -c fluent.conf --dry-run`. Review logs: `sudo journalctl -u td-agent -n 100`. Verify file permissions on config and buffer directories.
Logs not being collected	Verify `pos_file` exists and is writable. Check file path patterns match actual log locations. Ensure log files have read permissions. Test with `tail -f` on the log file.
High memory usage	Switch from memory buffers to file buffers. Reduce `chunk_limit_size` and `queue_limit_length`. Enable multi-worker mode to distribute load. Check for memory leaks in custom plugins.
Buffer queue growing	Increase `flush_interval` or reduce log volume. Check downstream system capacity (Elasticsearch, S3). Verify network connectivity. Review `retry_max_interval` settings.
Logs being dropped	Check buffer `overflow_action` setting. Increase `queue_limit_length` and `chunk_limit_size`. Monitor disk space for file buffers. Review `retry_timeout` configuration.
Plugin installation fails	Ensure Ruby development headers installed: `sudo apt-get install ruby-dev build-essential`. Use correct gem command: `td-agent-gem` not `gem`. Check plugin compatibility with Fluentd version.
Parse errors in logs	Validate parser configuration with sample logs. Use `@type regexp` with proper regex patterns. Add error handling: `emit_invalid_record_to_error true`. Check time format strings.
Cannot connect to Elasticsearch	Verify Elasticsearch is running: `curl http://elasticsearch:9200`. Check firewall rules. Validate credentials if using authentication. Review Elasticsearch logs for rejection reasons.
Duplicate logs appearing	Check `pos_file` location is persistent across restarts. Verify only one Fluentd instance is running. Review `read_from_head` setting (should be `false` in production).
Slow log processing	Enable multi-worker mode. Optimize regex patterns in filters. Use `@type grep` before expensive parsers. Profile with `--trace` flag to identify bottlenecks.
SSL/TLS connection errors	Verify certificate paths and permissions. Check certificate expiration dates. Ensure CA bundle is up to date. Use `verify_ssl false` for testing only (not production).